Maaz Zindani

Loading the index…

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

Node.js exits with code 13 and an unsettled top-level await warning

ErrorWarning: Detected unsettled top-level await

Short answer

Node.js ends the process with exit code 13 when a top-level await waits on a promise that nothing can ever settle. Find the awaited promise, then make sure its resolve or reject is reachable: a missing callback, an event already emitted, or no cancel path.

  • Applies to Node.js 22, Node.js 24, ES modules
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Confirm the exit code, then add a log line before and after each top-level await to see which one never returns.

    node app.mjs; echo "exit code: $?"
  2. 2Match what you see, then jump to its fix

    1. 1The last log line printed is the one just before an await new Promise(...)The promise executor never calls resolve or rejectFix
    2. 2await once(emitter, 'ready') hangs although the emitter does emit ready, just earlierAwaiting an event that was already emittedFix
    3. 3The awaited event can legitimately never happenWaiting with no way outFix

What does the error look like?

  • Warning: Detected unsettled top-level await
  • Process exits with status 13

Cause 1 of 3

The promise executor never calls resolve or reject

1Check

Read the executor. A callback API wrapped in a Promise often forgets to call resolve on one branch.

grep -n "new Promise" -A8 app.mjs

2Fix

Settle the promise on every path, including the error path.

const data = await new Promise((resolve, reject) => {
  legacyRead(path, (err, result) => {
    if (err) return reject(err);
    resolve(result);
  });
});

3Verify

Run again. The exit code should be 0.

node app.mjs; echo "exit code: $?"

Confirmed by nodejs.org

Did this fix it?

Cause 2 of 3

Awaiting an event that was already emitted

1Check

events.once only settles for events emitted after it is called. An event emitted earlier, or between two awaits, is missed.

grep -n "once(" app.mjs

2Fix

Create every promise first, then await them together.

import { once } from 'node:events';
const ready = once(server, 'listening');
const failed = once(server, 'error');
server.listen(3000);
await ready;

3Verify

Run again and check the process continues past the await.

node app.mjs

Confirmed by nodejs.org

Did this fix it?

Cause 3 of 3

Waiting with no way out

1Check

A promise that waits for an event needs a cancel path, or the process will end silently with code 13.

grep -n "await once" app.mjs

2Fix

Pass an AbortSignal, abort it after a time limit, and catch the AbortError.

import { once } from 'node:events';
const ac = new AbortController();
const timer = setTimeout(() => ac.abort(), 10_000);
try {
  await once(emitter, 'done', { signal: ac.signal });
} catch (err) {
  if (err.name !== 'AbortError') throw err;
  console.error('gave up waiting for done');
} finally {
  clearTimeout(timer);
}

3Verify

Trigger the case where the event never fires and see the message instead of a silent exit.

node app.mjs; echo "exit code: $?"

Confirmed by nodejs.org

Did this fix it?

How do I stop it coming back?

  • Wrap callback APIs with a promise helper and settle on every branch.
  • Create event promises before triggering the work that emits the event.
  • Put a time limit on any await that depends on outside input.

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

ng serve says it cannot determine the project or target

Cannot determine project for command.

The Angular CLI looked through angular.json for a project that defines the target you asked for (serve, build, test) and found none, or found several and could not pick one.

3 causes, each with a fix

Back end

ng serve cannot find the dev-server builder package

Could not find the implementation for builder @angular/build:dev-server

The builder named in angular.json (for example @angular-devkit/build-angular:dev-server) is looked up as an npm package starting from the workspace root.

3 causes, each with a fix

Next step

Want this handled for good?

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