Troubleshooting Overview

If you experience an issue when using CockroachDB, try these steps to resolve the problem:

Check your logs for errors. 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.
- Consult the list of common errors and solutions.
- If you are getting transaction retry errors, see client-side retry handling and the Transaction Retry Error Reference.
If the problem doesn’t match a common error, try the following pages:
- Troubleshoot Cluster Setup helps you start and scale your cluster.
- Troubleshoot Common Problems helps you handle errors and troubleshooting problems that may arise during application development.
- Troubleshoot Statement Behavior helps you with unexpected query results.
If you are using Cockroach Cloud, see the errors and solutions in Troubleshoot CockroachDB Cloud.
If you see discrepancies in metrics, refer to Differences in Metrics between Third-Party Monitoring Integrations and DB Console.
The critical nodes endpoint lets you query the status of your cluster’s data replication, data placement, and zone constraint conformance.
If you believe replicas are not behaving as specified by your zone configurations, whether in terms of data placement or zone constraint conformance, see Troubleshoot Replication Zones.
If you cannot resolve the issue yourself, the following tools can help you move forward:
- Support Resources identify ways you can get help with troubleshooting.
In a support escalation, you may be directed to use the following features by the Cockroach Labs support team: