Maaz Zindani

Loading the index…

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

Knex runs out of connections and the query waits until it times out

ErrorKnex: 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.

  • Applies to Knex, Node.js 22, PostgreSQL, MySQL
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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/null
  2. 2Match what you see, then jump to its fix

    1. 1The error shows up after a few requests and never recovers until the process restartsA transaction is left openFix
    2. 2The transaction itself looks right, but a query in it calls knex('table') and waitsQueries inside a transaction use knex instead of trxFix
    3. 3Errors appear only under load, and the code has no open transactionsThe pool is smaller than the real concurrencyFix

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 -20

2Fix

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/orders

Confirmed by knexjs.org

Did this fix it?

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 -20

2Fix

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/orders

Confirmed by knexjs.org

Did this fix it?

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

Did this fix it?

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:

Related fixes

Next step

Want this handled for good?

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