node-postgres pool times out waiting for a client
Error: timeout exceeded when trying to connectShort 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.
Fix it fast
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/2Match what you see, then jump to its fix
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/1Confirmed by node-postgres.com
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/1Confirmed by node-postgres.com
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
Back end
Knex runs out of connections and the query waits until it times out
Knex: Timeout acquiring a connection. The pool is probably full. Are you missing a .transacting(trx) call?
Every query needs a free connection from Knex's pool.
3 causes, each with a fixBack end
Node.js cannot reach PostgreSQL: connect ETIMEDOUT in production
at TCPConnectWrap.afterConnect [as oncomplete]
ETIMEDOUT means the other side never answered the connection attempt.
3 causes, each with a fixBack end
node-postgres: SCRAM-SERVER-FIRST-MESSAGE client password must be a string
SASL: SCRAM-SERVER-FIRST-MESSAGE: client password must be a non-empty string
The server asked for SCRAM authentication and node-postgres had no string to hash.
4 causes, each with a fixBack end
PostgreSQL error: bind message has N parameter formats but 0 parameters
QueryFailedError: bind message has N parameter formats but 0 parameters
One query is carrying more bound values than the Postgres protocol can describe.
2 causes, each with a fixBack end
Node.js gets 'no pg_hba.conf entry for host' from PostgreSQL
error: no pg_hba.conf entry for host
The server found no pg_hba.conf rule matching your connection type, address, database and user, so it denied access.
3 causes, each with a fixBack end
Prisma Client fails with Invalid prisma.user.findUnique() invocation
The table `{table}` does not exist in the current database.
The first line, Invalid prisma.user.findUnique() invocation, only says which call failed.
4 causes, each with a fix