Node.js exits with code 13 and an unsettled top-level await warning
Warning: Detected unsettled top-level awaitShort 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.
Fix it fast
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: $?"2Match what you see, then jump to its fix
- 1
The last log line printed is the one just before an await new Promise(...)The promise executor never calls resolve or rejectFix - 2
await once(emitter, 'ready') hangs although the emitter does emit ready, just earlierAwaiting an event that was already emittedFix - 3
The awaited event can legitimately never happenWaiting with no way outFix
- 1
What does the error look like?
Warning: Detected unsettled top-level awaitProcess 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.mjs2Fix
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
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.mjs2Fix
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.mjsConfirmed by nodejs.org
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.mjs2Fix
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
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 fixBack end
ng fails with Cannot find module @angular/cli/bin/ng
Cannot find module '@angular/cli/bin/ng'
The ng command is the entry point to the Angular CLI package.
2 causes, each with a fixBack end
Angular app shows 'Cannot GET /' when served by a Node.js server
Cannot GET /dashboard
Cannot GET / is Express saying no route or file matches the request.
3 causes, each with a fixBack 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 fixBack end
Angular build says it cannot resolve '@angular/localize/init'
Can't resolve '@angular/localize/init' in '/usr/src/app/src'
The build imports @angular/localize, and that package is not in node_modules.
2 causes, each with a fixBack end
The command npm run build -- --prod exited with code 1 (Angular)
The command "npm run build -- --prod" exited with code 1
Exit code 1 only says the build failed; the real message is above it.
2 causes, each with a fix