Documentation: make error messages actionable for non-experts

[knackstedt]

Description

During my 1.x.x => 2.x.x upgrade process, I ran into several error messages that were simply confusing.

ResponseError: Live Query was made, but is not supported

When I switched to 2.0.0 I started getting this, and I found in Discord that this seems to mean that I need to use the ws/wss protocol for live queries to work. I tried changing the URI that I connect to to start with ws and I made various permutations of connection string and saw the following other errors. It would be nice to have it note that instead of "this feature is disabled". I was only able to find any reference to the fix via Discord, which is not searchable via public search engines.

VersionRetrievalFailure: Failed to retrieve remote version. If the server is behind a proxy, make sure it's configured correctly.

This error shows up when I used the wss:// protocol. I'm guessing that it was due to the fact I never set a certificate on Surreal, which I understand but the error is misleading. It would be nice to have the HTTP/TCP error propagated up so I can tell what the underlying network problem was.

The engine reported the connection to SurrealDB has dropped

This error message isn't helpful. It would help to know why the connection was dropped. I'm assuming it's due to my connection URI but I'm not totally sure as the error doesn't give me any diagnostic information.

ConnectionUnavailable: There is no connection available at this moment

This error message is somewhat helpful, but doesn't make it clear what's causing a connection to be unavailable.

Note: The cause of these errors appears to be a bug in something, this issue is specifically to cover making the error messages more meaningful, not resolving the errors themselves.

Is there an existing issue for this?

• I have searched the existing issues

Code of Conduct

• I agree to follow this project's Code of Conduct