Warning:
This version of CockroachDB is no longer supported. Cockroach Labs supports the current stable release and two releases prior. Please use one of these supported versions.

This page helps with general troubleshooting steps that apply to many different scenarios, such as not being able to connect to a node.

Note:
If you cannot find what you're looking for, we also have more detailed troubleshooting steps for specific issues.

Common Troubleshooting Steps

If you run into issues with CockroachDB, there are a few steps you can always take:

  • Check your logs for errors related to your issue. Logs are generated on a per-node basis, so you must either identify the node where the issue occurred or collect the logs from all active nodes in your cluster.

  • Stop and restart problematic nodes with the --logtostderr flag. This option prints logs to your terminal through stderr, letting you see all of your cluster's activities as they occur.

Common Errors

getsockopt: connection refused Error

This error indicates that the cockroach binary is either not running or is not listening on the interfaces (i.e., hostname or port) you specified.

To resolve this issue, you must do one of the following:

If you're not sure what the --host and --port values might have been, you can kill the cockroach process, and then restart the node:

$ pkill cockroach
$ cockroach start [flags]

Replication Error in a Single-Node Cluster

When running a single-node CockroachDB cluster, an error about replicas failing will eventually show up in the node's log files, for example:

E160407 09:53:50.337328 storage/queue.go:511  [replicate] 7 replicas failing with "0 of 1 store with an attribute matching []; likely not enough nodes in cluster"

This error occurs because CockroachDB expects three nodes by default. If you do not intend to add additional nodes, you can stop this error by updating your default zone configuration to expect only one node:

# Insecure cluster:
$ cockroach zone set .default --insecure --disable-replication

# Secure cluster:
$ cockroach zone set .default --certs-dir=[path to certs directory] --disable-replication

The --disable-replication flag automatically reduces the zone's replica count to 1, but you can do this manually as well:

# Insecure cluster:
$ echo 'num_replicas: 1' | cockroach zone set .default --insecure -f -

# Secure cluster:
$ echo 'num_replicas: 1' | cockroach zone set .default --certs-dir=[path to certs directory] -f -

See Configure Replication Zones for more details.

Something Else?

If we do not have a solution here, you can try using our other support resources, including:



Yes No