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
const pool = createPool({ host: 'db.example.com', port: 5432, connectionTimeoutMillis: 1000 });
const client = await pool.connect(); // throws ConnectionTimeoutErrorconst 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
- Database Connections
Learn about database connections.