Maaz Zindani

Loading the index…

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

Jest finishes the tests but a worker keeps running and is force exited

ErrorA worker process has failed to exit gracefully and has been force exited.

Short answer

Something your tests started is still alive when the tests end: a listening server, a database connection or a timer. Jest cannot stop the worker until that handle closes, so it kills it. Find the handle with --detectOpenHandles, then close it in afterAll. Do not hide it with --forceExit.

  • Applies to Jest 30, Node.js 22, Node.js 24, Express 5
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Run Jest once with open-handle detection. It prints where each leaked resource was created. It runs tests serially, so it is slower; use it only to debug.

    npx jest --detectOpenHandles
  2. 2Match what you see, then jump to its fix

    1. 1--detectOpenHandles points at the line with app.listenThe test starts an HTTP server and never closes itFix
    2. 2--detectOpenHandles lists a Timeout or an Immediate created by your codeA timer or interval is still pendingFix
    3. 3--detectOpenHandles points at a connection created in a beforeAll or at import timeA database or other external connection stays openFix

What does the error look like?

  • A worker process has failed to exit gracefully and has been force exited.

Cause 1 of 3

The test starts an HTTP server and never closes it

1Check

Search for app.listen in files the tests import. A server that listens at import time stays open for the whole run.

grep -rn "\.listen(" src

2Fix

Export the app without listening, listen only in a separate start file, and when a test does start a server, close it in afterAll and wait for the callback.

let server;
beforeAll((done) => { server = app.listen(0, done); });
afterAll((done) => { server.close(done); });

3Verify

Run the suite again; the warning should be gone.

npx jest

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

A timer or interval is still pending

1Check

setInterval for polling, cache cleanup or rate-limit stores keeps the event loop alive for as long as it is active.

grep -rn "setInterval\|setTimeout" src

2Fix

Store the timer and clear it in a teardown hook, or call unref() on timers that must not keep the process alive.

const timer = setInterval(cleanup, 60000);
timer.unref();

3Verify

Run Jest with open-handle detection again and confirm the list is empty.

npx jest --detectOpenHandles

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

A database or other external connection stays open

1Check

Look for pools and clients opened by tests or by the modules they import, with no matching close.

grep -rn "connect(\|createPool\|new Pool" src

2Fix

Close the connection in afterAll and return the promise, so Jest waits for it. The CLI docs say to tear down external resources after each test, and treat --forceExit as an escape hatch.

afterAll(async () => {
  await db.end();
});

3Verify

Run the full suite and watch for the message.

npx jest

Confirmed by jestjs.io

Did this fix it?

How do I stop it coming back?

  • Keep app creation and app.listen in separate files so tests import the app only.
  • Run --detectOpenHandles in CI when the warning first appears, not months later.
  • Use --runInBand only to compare behaviour, not as the permanent fix.

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.