Skip to content

Connection timeout: database unreachable

Quick summary

Your application tried to connect to the database but the connection timed out — the server may be down or network is blocked.

Why this happens

  • The database server is down or not listening on the expected port

  • A firewall or network issue blocks the connection between the application and the database

  • The connection pool is exhausted and no connections are available within the timeout

Minimal example

✗ Broken code
const pool = createPool({ host: 'db.example.com', port: 5432, connectionTimeoutMillis: 1000 });
const client = await pool.connect(); // throws ConnectionTimeoutError
✓ Fixed code
const pool = createPool({ host: 'db.example.com', port: 5432, connectionTimeoutMillis: 5000, max: 20 });
async function getClientWithRetry() {
  for (let i = 0; i < 3; i++) {
    try { return await pool.connect(); }
    catch (e) { await new Promise(r => setTimeout(r, 1000 * 2 ** i)); }
  }
  throw new Error('DB unavailable after retries');
}

Increasing the timeout and adding retry logic with exponential backoff handles transient connection failures gracefully.

How to diagnose

  • Verify the database server is running with a ping or telnet to the host and port

  • Check the connection string for correct host, port, and credentials

  • Review the connection pool settings and current active connection count

How to fix

  • Start the database server or contact the database administrator

  • Fix network connectivity or firewall rules to allow the connection

  • Increase the pool size or connection timeout, and add retry logic with exponential backoff

How to prevent

  • Use connection pooling with health checks and automatic reconnection

  • Monitor database connectivity and set up alerts for connection failures

Related Resources

Related Glossary

Related Lessons

← Back to language