This page helps with general troubleshooting steps that apply to many different scenarios, such as not being able to connect to a node.
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 throughstderr
, 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:
- Start your CockroachDB node.
- If you specified a
--host
flag when starting your node, you must include it with all othercockroach
commands. - If you specified a
--port
flag when starting your node, you must include it with all othercockroach
commands or change theCOCKROACH_PORT
environment variable.
If you're not sure what the --host
and --port
values might have been, you can end 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: