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?Short answer
Every query needs a free connection from Knex's pool. The error means all connections stayed busy for the whole acquire timeout. The common cause is a transaction that never commits or rolls back, or queries inside it that skip the trx object. Fix that first, then size the pool.
Fix it fast
1Find out which cause you have
Look at the pool settings you use. If none are set, the pool defaults apply: a maximum of 10 connections and an acquire timeout of 60 seconds.
grep -rn "pool\|acquireConnectionTimeout" knexfile.js src/db* 2>/dev/null2Match what you see, then jump to its fix
- 1
The error shows up after a few requests and never recovers until the process restartsA transaction is left openFix - 2
The transaction itself looks right, but a query in it calls knex('table') and waitsQueries inside a transaction use knex instead of trxFix - 3
Errors appear only under load, and the code has no open transactionsThe pool is smaller than the real concurrencyFix
- 1
What does the error look like?
Knex: Timeout acquiring a connection. The pool is probably full. Are you missing a .transacting(trx) call?
Cause 1 of 3
A transaction is left open
1Check
If you use the trx object without a handler that returns a promise, you must call trx.commit or trx.rollback yourself. A path that skips both, such as an early return or a thrown error, holds the connection forever.
grep -rn "knex.transaction\|transaction(" src/ | head -202Fix
Use the handler form, where Knex commits when the returned promise resolves and rolls back when it throws. If you use the manual form, finish with commit or rollback in try and catch.
await knex.transaction(async (trx) => {
await trx('orders').insert({ total: 10 });
await trx('stock').decrement('qty', 1).where({ id: 5 });
});3Verify
Run the route many times in a row. It no longer starts to time out.
npx autocannon -c 20 -a 200 http://localhost:3000/ordersConfirmed by knexjs.org
Cause 2 of 3
Queries inside a transaction use knex instead of trx
1Check
All queries of a transaction run on its one connection, but only when they go through trx. A query on knex asks the pool for a second connection, and with the pool full of waiting transactions none is free.
grep -rn "await knex(" src/ | head -202Fix
Inside the handler, run every query on trx, including helper functions you call from it. Pass trx in as an argument.
async function addOrder(trx, data) {
return trx('orders').insert(data);
}
await knex.transaction(async (trx) => {
await addOrder(trx, { total: 10 });
});3Verify
Run the same load as before and watch it stay quiet.
npx autocannon -c 20 -a 200 http://localhost:3000/ordersConfirmed by knexjs.org
Cause 3 of 3
The pool is smaller than the real concurrency
1Check
The default pool for PostgreSQL and MySQL is min 2 and max 10. More than ten overlapping slow queries make the next ones wait for a free slot.
SHOW max_connections;2Fix
Raise pool.max within what the database allows across all app instances, and set min to 0. Shorten slow queries first, because a bigger pool only moves the limit.
const knex = require('knex')({
client: 'pg',
connection: process.env.DATABASE_URL,
pool: { min: 0, max: 20 },
acquireConnectionTimeout: 60000,
});3Verify
Repeat the load test. The error is gone while the database connection count stays under its limit.
SELECT count(*) FROM pg_stat_activity;Confirmed by knexjs.org
How do I stop it coming back?
- Use the handler form of knex.transaction so commit and rollback are automatic.
- Pass trx to every function that runs inside a transaction.
- Keep transactions short: no HTTP calls or slow work between their queries.
- Call knex.destroy() in scripts and tests so the process can exit.
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:
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- WorkforceA field app, an admin console and a self-hosted Node.js server for push and reconciliation.
Related fixes
Back end
node-postgres pool times out waiting for a client
Error: timeout exceeded when trying to connect
The pool has no free client to give you.
2 causes, each with a fixDatabases
MySQL says Too many connections to a Node.js app
Too many connections
MySQL refuses new clients once max_connections slots are in use.
3 causes, each with a fixBack end
TypeORM connects but creates no tables or columns
A new column is missing, with no error at startup
TypeORM does not create tables by itself.
3 causes, each with a fixBack end
Node.js in Docker Compose cannot reach MySQL on 127.0.0.1:3306
Error: connect ECONNREFUSED 127.0.0.1:3306
Inside a container, 127.0.0.1 is that container, not MySQL.
3 causes, each with a fixBack end
Go database/sql fails to scan a NULL column, and stores empty strings instead of NULL
unsupported Scan, storing driver.Value type <nil> into type *string
database/sql hands a NULL to Scan as nil, and a plain *string cannot hold it, so Scan returns an error.
2 causes, each with a fixBack end
The mysql package says it cannot enqueue a Handshake after quit
code: 'PROTOCOL_ENQUEUE_AFTER_QUIT'
The message means connection.end() was already called on that connection object, and something later tried to use or connect it again.
2 causes, each with a fix