Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Databases and Redis

Sequelize fails with 'Operation timeout' while waiting for a connection

ErrorSequelizeConnectionAcquireTimeoutError: Operation timeout

Short answer

This error means Sequelize waited the full acquire time and no connection in its pool became free. The pool is small (5 connections by default), so the usual reasons are too many concurrent requests, slow queries, transactions that were never committed or rolled back, or network calls made inside a transaction. Find what holds the connections, then fix that.

  • Applies to Sequelize 6 (pool guide from the v7 docs), Node.js 22, PostgreSQL (for the session queries)
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Ask the database what its sessions are doing while the errors happen. On PostgreSQL, sessions that stay in the state 'idle in transaction' point to transactions your code started and did not finish. Other databases have an equivalent session list.

    SELECT state, xact_start, state_change, query
    FROM pg_stat_activity
    WHERE state = 'idle in transaction';
  2. 2Match what you see, then jump to its fix

    1. 1Rows with state idle in transaction and an old xact_start; the errors grow over time until the app is stuckTransactions that are never committed or rolled backFix
    2. 2Sessions in idle in transaction for seconds, and they match the time an HTTP call or a file upload takesNetwork calls or slow work happen while a transaction is openFix
    3. 3Sessions stay in the active state for a long time, and the errors appear in bursts when a certain route is calledSome queries are slow, so requests pile up behind themFix
    4. 4Everything is fast and no session is stuck, but the errors show up when many requests arrive at onceThe pool is simply too small for the concurrent requestsFix
    5. 5Errors on AWS Lambda with a small max, mostly on invocations after a slow or timed-out oneA serverless function reuses a frozen connection poolFix

What does the error look like?

  • SequelizeConnectionAcquireTimeoutError: Operation timeout
  • ConnectionAcquireTimeoutError

Cause 1 of 5

Transactions that are never committed or rolled back

1Check

A manual transaction holds its connection until you call commit() or rollback(). Any code path that returns or throws between the start and the end of an unmanaged transaction leaks one connection. Search for transactions that are created without a callback.

grep -rn "sequelize.transaction(" src/

2Fix

Use a managed transaction: Sequelize commits when the callback finishes and rolls back when it throws, and releases the connection either way. If you must stay manual, call rollback() in the catch block and commit() on success, on every path.

await sequelize.transaction(async (t) => {
  await User.create({ firstName: 'Bart' }, { transaction: t });
  await Account.create({ owner: 'Bart' }, { transaction: t });
});

3Verify

Run the same load again and re-run the first-step query. No session stays idle in transaction.

SELECT state, xact_start, state_change, query
FROM pg_stat_activity
WHERE state = 'idle in transaction';

Confirmed by sequelize.org

Did this fix it?

Cause 2 of 5

Network calls or slow work happen while a transaction is open

1Check

The pool guide warns that a network request inside a transaction keeps the transaction, and with it the connection, open for as long as that request takes. Look for await calls to other services between the first and last query of a transaction.

grep -rn -A8 "sequelize.transaction(" src/ | grep -n "fetch\|axios\|http"

2Fix

Do the slow work before the transaction starts or after it ends, so the transaction contains only database calls. Where a call cannot move, put a timeout on it.

const data = await fetchPrices();          // slow call first, outside the transaction
await sequelize.transaction(async (t) => {
  await Price.bulkCreate(data, { transaction: t });
});

3Verify

Re-run the first-step query under load. Transactions now last for milliseconds.

SELECT state, xact_start, state_change, query
FROM pg_stat_activity
WHERE state = 'idle in transaction';

Confirmed by sequelize.org

Did this fix it?

Cause 3 of 5

Some queries are slow, so requests pile up behind them

1Check

The pool guide names slow queries as a cause: while they run, their connections are busy and new requests wait for the acquire timeout. Look at the longest running active query.

SELECT xact_start, state, query
FROM pg_stat_activity
WHERE state = 'active'
ORDER BY xact_start;

2Fix

Read the execution plan the database makes for the slow statement and optimize it. Fixing the query frees the connection sooner, which is better than making the pool bigger.

-- paste the slow statement from the query column after EXPLAIN
EXPLAIN SELECT * FROM orders WHERE customer_id = 42;

3Verify

The longest active query shrinks and the errors stop under the same traffic.

SELECT xact_start, state, query
FROM pg_stat_activity
WHERE state = 'active'
ORDER BY xact_start;

Confirmed by sequelize.org

Did this fix it?

Cause 4 of 5

The pool is simply too small for the concurrent requests

1Check

By default the pool holds at most 5 connections, and each Sequelize instance has its own pool. Every process or container you run adds its own pool, so what counts is the total across all of them against the database's connection limit.

grep -rn "pool" src/config/ src/models/ 2>/dev/null

2Fix

Raise max, and split the database's connection limit between your processes. The guide's example reserves some connections for other uses and divides the rest by the number of processes.

const sequelize = new Sequelize(process.env.DATABASE_URL, {
  pool: { max: 20, min: 0, acquire: 30000, idle: 10000 },
});

3Verify

Restart the app and repeat the load test. The error is gone, and the database does not refuse new connections.

SELECT count(*) FROM pg_stat_activity;

Confirmed by sequelize.org

Did this fix it?

Cause 5 of 5

A serverless function reuses a frozen connection pool

1Check

The Sequelize Lambda guide explains that with max set to 1 a slow query blocks the next ones, and that after a timeout the paused event loop can leave a connection that was never returned to the pool, so later invocations of a reused container fail with this error.

grep -rn "new Sequelize" src/

2Fix

Use the guide's pool settings for Lambda and close or restart the pool as it shows. Keep max times your expected concurrent invocations below the database limit.

const sequelize = new Sequelize(process.env.DATABASE_URL, {
  pool: {
    max: 2,
    min: 0,
    idle: 0,
    acquire: 3000,
    evict: CURRENT_LAMBDA_FUNCTION_TIMEOUT, // the function timeout in ms
  },
});

3Verify

Invoke the function several times in a row, including after a slow call. The error no longer appears, and the connection count in the database falls back after the burst.

SELECT count(*) FROM pg_stat_activity;

Confirmed by sequelize.org

Did this fix it?

How do I stop it coming back?

  • Prefer managed transactions, so no code path can forget to commit or roll back.
  • Keep network calls and file work outside transactions.
  • Size pool.max from the database's connection limit divided by the number of running processes, not from the default.
  • Watch pg_stat_activity (or your database's session list) for sessions that stay idle in transaction.

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.