Troubleshoot connections
Drivers that do not connect, do not authenticate or do not trust the certificate.
These are the connection problems seen most often. For each one you have the cause, how to confirm it on your machine, how to fix it and what to do so it does not happen again.
The connection closes before authenticating
It is the most common failure. Your application opens the connection to the node, the node cuts it as soon as it gets the first bytes in clear text and the driver reports that the server closed the connection before asking for the user or the password.
Cause
The TeselaDB client port only accepts connections over TLS, and your application's connection string does not carry
tls=true.
How to confirm it
Look at the string. If tls=true is not among the options after the question mark, this is the problem.
Fix
Add tls=true to the options of the string, along with tlsCAFile if your driver accepts it, and start the
application again.
How to avoid it
Always start from the string in Connection string and options, which already carries the TLS options the node asks for.
The driver does not trust the node certificate
Here TLS is on. The connection reaches the node and drops during the TLS handshake, before the driver sends any command, because the driver does not recognise the authority that signed the certificate the node presents.
Cause
The node presents a certificate signed by your cluster's CA, and the driver does not have that CA among the authorities it trusts.
How to confirm it
The driver's error mentions certificate verification: an incomplete chain of trust or an authority it does not recognise.
Fix
Give the driver the cluster's pki/ca.pem file with the tlsCAFile option. In Java and .NET the driver does not read
that option, so put the CA in the trust store of the virtual machine or of the system.
How to avoid it
Copy pki/ca.pem to each application machine as soon as you create the cluster, the same way you copy the connection
string.
Authentication fails
The network and TLS work. The TLS handshake completes, but the node rejects the credentials the driver sends and the application never gets to read or write a single document.
Cause
The user, the password or the authentication database in the string do not match a user that exists in the cluster.
How to confirm it
The driver returns the AuthenticationFailed error, with code 18, when it opens the connection or on the first
operation.
Fix
Check the user name, its password and the authSource option, which has to be the database where you created that
user.
How to avoid it
Keep each application's credentials in your secrets manager and have the application read them from there at start-up.