Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Node.js, PHP and APIs

node-postgres pool times out waiting for a client

ErrorError: timeout exceeded when trying to connect

Short answer

The pool has no free client to give you. Either code checked clients out with pool.connect and never released them, or more queries run at once than the pool allows (10 by default). Release clients in a finally block, use pool.query for single queries, and size max on purpose.

  • Applies to pg 8, Node.js 22, PostgreSQL 16
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    List every place that checks out a client. Each one needs a matching release.

    grep -rn "pool.connect\|client.release" src/
  2. 2Match what you see, then jump to its fix

    1. 1Works at first, then every request fails or hangs after a few callsA client is checked out and never releasedFix
    2. 2Errors appear only under load; with connectionTimeoutMillis at 0 requests hang insteadMore concurrent work than the pool allows, and no timeout setFix

What does the error look like?

  • Error: timeout exceeded when trying to connect

Cause 1 of 2

A client is checked out and never released

1Check

The pooling guide says an unreleased client leaks, and eventually the pool is empty and later checkouts wait forever. Look for return or throw paths between connect and release.

grep -rn -B2 -A12 "pool.connect" src/

2Fix

Release in a finally block, or switch single queries to pool.query, which checks out and releases for you.

const client = await pool.connect();
try {
  const res = await client.query('SELECT * FROM users WHERE id = $1', [1]);
  return res.rows[0];
} finally {
  client.release();
}

3Verify

Send more requests than the pool size and check they all finish.

npx autocannon -c 30 -d 20 http://127.0.0.1:3000/users/1

Confirmed by node-postgres.com

Did this fix it?

Cause 2 of 2

More concurrent work than the pool allows, and no timeout set

1Check

max defaults to 10 clients and connectionTimeoutMillis defaults to 0, which means no timeout.

grep -rn "new Pool" src/

2Fix

Set max to what your database allows, and set connectionTimeoutMillis so a stuck checkout fails with an error you can see.

const pool = new Pool({
  max: 20,
  connectionTimeoutMillis: 5000,
});

3Verify

Run the load test again and watch for errors.

npx autocannon -c 30 -d 20 http://127.0.0.1:3000/users/1

Confirmed by node-postgres.com

Did this fix it?

How do I stop it coming back?

  • Prefer pool.query for single statements.
  • Keep transactions on one client from pool.connect, and release it in finally.
  • Add a pool.on('error') listener.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.