Skip to content

Connection Timeout

Error message

                timeout expired while waiting for connection
              

Quick summary

The connection pool had no available connections and your request waited longer than the configured timeout.

Why this happens

  • The connection pool is too small for the current load

  • Connections are being leaked (not returned to the pool)

  • Long-running queries are tying up connections

  • The database is slow or unreachable, causing connections to hang

Minimal example

✗ Broken code
// Connection not returned to the pool
const conn = await pool.getConnection();
const result = await conn.query('SELECT * FROM users');
// forgot conn.release() → connection leak
✓ Fixed code
const conn = await pool.getConnection();
try {
  const result = await conn.query('SELECT * FROM users');
  return result;
} finally {
  conn.release(); // always release
}

Using try/finally ensures the connection is always returned to the pool, even if the query fails.

How to diagnose

  • Check the pool size and current connection count

  • Look for connection leaks — queries that do not release connections

  • Check for long-running queries that hold connections

  • Monitor pool wait times and connection usage patterns

How to fix

  • Increase the connection pool size

  • Fix connection leaks — ensure all connections are released

  • Add query timeouts to prevent long-running queries from holding connections

  • Optimize slow queries to free up connections faster

How to prevent

  • Always use try/finally or connection pool helpers that auto-release connections

  • Set appropriate query timeouts

  • Monitor pool metrics and adjust pool size based on load

  • Use async/await patterns that automatically return connections

Related Resources

Related Glossary

Related Lessons

← Back to language