CockroachDB Connection Refused / Cannot Connect Fix

How to fix it

// try these in order, the most common fix is first

1. FIX 1Check the node

   Copy steps
   1. 01Run cockroach node status --certs-dir=... or check the process and logs
   2. 02Restart a crashed node and check for OOM kills in system logs
   Did this fix it? Yes No

2. FIX 2Check address and ports

   Copy steps
   1. 01Confirm the connection string host, port 26257 and sslmode
   2. 02Verify --listen-addr and --advertise-addr are reachable from the client
   3. 03Open 26257 in firewalls and security groups
   Did this fix it? Yes No

3. FIX 3Check certificates

   Copy steps
   1. 01Verify CA and node certs with cockroach cert list
   2. 02Make sure the host name is in the node certificate SANs
   3. 03Renew expired certificates
   Did this fix it? Yes No

4. FIX 4Cloud clusters

   Copy steps
   1. 01Add your IP to the network allowlist or use a private connection
   2. 02Copy the connection string from the Cloud Console, including the cluster CA cert
   Did this fix it? Yes No

Symptoms

dial tcp connection refused; failed to connect to host; x509 certificate errors; client can reach the DB Console (8080) but not SQL (26257).

Why it happens

• C-01Node or process not running or crashed (out of memory)
• C-02Wrong host, port (SQL 26257, DB Console 8080) or --listen-addr/--advertise-addr
• C-03Firewall, security group or load balancer blocking 26257
• C-04TLS certificate expired or not valid for the host name used
• C-05Cluster lost quorum so no node can serve requests
• C-06Cloud: IP allowlist does not include your address

// this guide also covers

• cockroachdb connection refused
• cockroachdb cannot connect
• cockroachdb x509 certificate error
• cockroachdb port 26257
• cockroachdb connection timeout

The same problem in other apps

All not loading, error messages & connection guides →

• PlanetScale Prisma Connection Errors (PlanetScale)

Other CockroachDB errors

• CockroachDB 'restart transaction' Error (40001) Fix
• CockroachDB Cluster Throttled: License Expired or No Telemetry
• Why Is CockroachDB Slow? Slow Query Fixes
• CockroachDB Node Down or Cluster Unavailable: Fix
• CockroachDB High Memory, CPU or OOM Crash Fix
• CockroachDB 'Not Supported' / Postgres Compatibility Errors Fix
• CockroachDB Cloud Bill Too High: How to Cut Costs
• How to Cancel or Downgrade CockroachDB Cloud