Troubleshoot CockroachDB Cloud

This page describes common CockroachDB Cloud errors and their solutions.

Connection errors

Cannot load certificates

You see the following error when you are using the cockroach sql command to connect to your CockroachDB Serverless cluster:

ERROR: cannot load certificates.
Check your certificate settings, set --certs-dir, or use --insecure for insecure clusters.

problem using security settings: no certificates found; does certs dir exist?
Failed running "sql"

Solution

Update to the latest CockroachDB client. You need to use v21.2.5 or later of the CockroachDB client to connect to your cluster without specifying the CA certificate path in the connection string.

Certificate signed by unknown authority

The following error is displayed when trying to connect to a cluster:

Error: x509: certificate signed by unknown authority
Failed running "sql"

There are two possible causes of this error: incorrect routing ID in the connection string, and CA certificate conflicts in the cockroach certificate search path.

Solution: incorrect routing ID in the connection string

Check if you are using the right routing ID in the connection method. You can find your routing ID in the CockroachDB Cloud Console by navigating to Cluster Overview > Connect > Select option/language and select General connection string, and then locating the parameter cluster={routing-id} in your connection string.

Solution: CA certificate conflicts

If you have existing certificates in ~/.cockroach-certs used to connect to CockroachDB Self-Hosted or CockroachDB Dedicated clusters and are trying to connect to a CockroachDB Serverless cluster using cockroach sql, you need download the CA cert by running the command from the Cluster Overview > Connect dialog if you have not already done so, and then set the sslrootcert parameter in the connection string you use when running cockroach sql.

For example, on Linux and Mac, set the sslrootcert parameter to $HOME/.postgresql/root.crt in the connection string:

cockroach sql --url "postgresql://maxroach@free-tier4.aws-us-west-2.cockroachlabs.cloud:26257/defaultdb?sslmode=verify-full&sslrootcert=$HOME/.postgresql/root.crt&options=--cluster%3Ddim-dog-2114"

Invalid cluster name in a third-party tool

The following error is displayed if you try to connect to a third-party tool with the wrong cluster or database name. The actual error message may vary depending on your tool:

FATAL: CodeParamsRoutingFailed: rejected by BackendConfigFromParams: Invalid cluster name

Solution

Check that you are using the correct cluster and database names. You can find these parameters in the CockroachDB Cloud Console by navigating to Cluster Overview > Connect > Step 2. Connect > Connection parameters. For most tools, the full name of your database should be in the format <routing-id>.<database> for CockroachDB Serverless clusters.

For connection examples with your tool, see these examples.

I/O timeout

The following error is most often caused by trying to connect to a cluster without authorizing the right network, not having an internet connection, or an issue in your application environment:

Is the server running?
If the server is running, check --host client-side and --advertise server-side.

dial tcp 35.196.33.161:26257: i/o timeout
Failed running "sql"

Solution

Check if you have internet access.

If you do have internet access, check if you have authorized the right network:

• In a development environment, you need to authorize your application server’s network and your local machine’s network. If you change your location, you need to authorize the new location’s network, or else the connection from that network will be rejected.

• In a production environment, you need to authorize your application server’s network.

• An i/o timeout can also be caused by firewall rules, which require your network administrator to investigate.

If neither of the above steps succeed, investigate your application's timeout value and environment:

• Increase the timeout value (e.g., from 5 seconds to 30 seconds) for your application's driver or framework and see if connection succeeds.

• If you can connect and run the same query in the SQL CLI, investigate your application environment.

• Investigate your network infrastructure to see if there is a network related performance problem, or contact support with these details.

No such host

The following error is displayed when you supply an incorrect host name:

ERROR: cannot dial server.
Is the server running?
If the server is running, check --host client-side and --advertise server-side.

dial tcp: lookup gcp-us-east4.crdb.io: no such host
Failed running "sql"

Solution

Check if you are using the correct host name.

You can find your host name in the CockroachDB Cloud Console by navigating to Cluster Overview > Connect > Step 2. Connect > Connection parameters and locating the Host field. If the error persists, contact Support.

Connection refused

The following error is displayed if your cluster connection is dropped:

Error: dial tcp 35.240.101.1:26257: connect: connection refused

Solution

CockroachDB Cloud connections can occasionally become invalid due to upgrades, restarts, or other disruptions. Your application should use a pool of persistent connections and connection retry logic to ensure that connections remain current. See the Production Checklist for more information.

External network access disabled

The following error is displayed if you try to access cloud storage from an organization without billing information on file:

ERROR: external network access is disabled

Solution

You must set up billing information for your organization to use cloud storage. If you don't have a credit card on file, you will be limited to userfile storage for bulk operations.

Deleted non-system databases

If you deleted all non-system databases on your cluster, you will see errors in the CockroachDB Cloud Console.

Solution

Connect to the system database using cockroach sql and create a new database.

1. Copy your connection string in the CockroachDB Cloud Console by navigating to Cluster Overview > Connect > Step 2. Connect > Connection string.

2. Change the database name in the connection string to system. For example, for the following connection string:

   postgresql://<username>:<password>@<serverless-host>:26257/defaultdb?sslmode=verify-full&options=--cluster%3D<routing-id>
   

   Change defaultdb to system.

   postgresql://<username>:<password>@<serverless-host>:26257/system?sslmode=verify-full&options=--cluster%3D<routing-id>
   

   Where:

   • <username> is the SQL user. By default, this is your CockroachDB Cloud account username.
   • <password> is the password for the SQL user. The password will be shown only once in the Connection info dialog after creating the cluster.
   • <serverless-host> is the hostname of the CockroachDB Serverless cluster.
   • <routing-id> identifies your tenant cluster on a multi-tenant host. For example, funny-skunk-123.

3. Connect to the cluster using the modified connection string with cockroach sql.

   cockroach sql --url "postgresql://<username>:<password>@<serverless-host>:26257/system?sslmode=verify-full&options=--cluster%3D<routing-id>"
   

   You will connect to the system database on your cluster.

4. Create a new defaultdb database.

   CREATE DATABASE IF NOT EXISTS defaultdb;
   

Security errors

Incorrect certs path

The following error is displayed if the directory path for the CA certificate is incorrect:

Error: open test-cluster-ca.crt: no such file or directory
Failed running "sql"

Solution

Check the directory path for the CA certificate in the connection method. If you have downloaded multiple CA certificates, check that you are using the right one.

Issue with CockroachDB workloads

The following error is displayed while trying to a run CockroachDB workload with sslmode=verify-full:

Error: x509: certificate signed by unknown authority

Solution

This is a known issue. Use sslmode=require instead.

Was this helpful?