skip to content

A job runner reports Node.js scripts exiting with codes 1, 7, 9 and 13: what does each code say about how the process ended?

level: middleimportance: should knowfreq 30%

answer

  1. Node documents its own exit codes
  2. one means nothing caught it
  3. one means the handler failed too
  4. a promise that never settled
  5. above 128 means a signal

basics

~20 s

Node exits 1 for an uncaught exception no handler took, 7 when the exception handler itself threw, 9 for an invalid command-line option, and 13 when top-level await never settled. Codes above 128 mean a fatal signal: 128 plus its number.

solid answer

~40 s

Node documents its own exit codes. **1** is an uncaught fatal exception that no `'uncaughtException'` handler took; under the default `--unhandled-rejections=throw` mode that includes an unhandled rejection, and the crash overrides any earlier `process.exitCode`. **7** means there was an uncaught exception and the fatal exception handler itself threw, typically your `'uncaughtException'` listener. **9** means `node` was given an unknown option, or an option that needs a value without one. **13** means top-level `await` in an ES module waited on a promise that never settled, so the loop emptied with the module still pending. Codes above 128 are fatal signals, 128 plus the signal number. For implicit codes such as 13, an explicit `process.exitCode` takes precedence; the uncaught-exception crash is the documented exception, forcing 1.

code

bash · 5 lines
bash
node -e 'setTimeout(() => { throw new Error("boom") }, 0)'; echo $?    # 1
node -e 'process.on("uncaughtException", () => { throw new Error("again") }); throw new Error("boom")'; echo $?    # 7
node --bogus-flag -e '0'; echo $?    # 9
node --input-type=module -e 'await new Promise(() => {})'; echo $?    # 13
node --input-type=module -e 'process.exitCode = 9; await new Promise(() => {})'; echo $?    # 9

go deeper

for a junior

Recall that 0 means success and 1 means an uncaught exception, and that codes above 128 come from signals.

for a middle

Explain the Node-specific codes, 7, 9 and 13, and the precedence rules between process.exitCode, process.exit() and the crash's own 1.

for a senior

Use exit codes to triage a fleet: a 0 after a crash points to a swallowing handler, a 7 to a broken handler, a 13 to an unsettled top-level await.

for a principal

Define an exit-code contract for a team's services and scripts that avoids Node's reserved values, so supervisors and alerts classify failures without reading logs.

## Node's own exit codes An **exit code** is the small integer a process hands to whoever started it: a shell's `$?`, a supervisor, a job runner. Node.js exits with **0** when no more asynchronous operations are pending and nothing set another code. Beyond that, Node documents a fixed list: | Code | Name in the Node docs | What usually causes it | |---|---|---| | 1 | Uncaught Fatal Exception | A throw or an unhandled rejection reached the loop with no handler | | 5 | Fatal Error | V8 hit an unrecoverable error; stderr usually shows a `FATAL ERROR` prefix | | 7 | Internal Exception Handler Run-Time Failure | An `'uncaughtException'` handler threw while handling an error | | 9 | Invalid Argument | An unknown option, or an option missing its required value | | 12 | Invalid Debug Argument | `--inspect` or `--inspect-brk` with an invalid or unavailable port | | 13 | Unsettled Top-Level Await | Top-level `await` on a promise that never settled | | 14 | Snapshot Failure | Building a V8 startup snapshot failed | | >128 | Signal Exits | A fatal signal: 128 plus the signal number | Codes 3, 4 and 10 are internal bootstrap failures that "generally can only happen during development of Node.js itself", and 6 means Node's internal fatal exception handler was somehow not a function. Codes 2 and 8 are unused; in older releases 8 sometimes meant an uncaught exception. ## How a crash chooses its code The rules that decide the code when something goes wrong: - **No handler:** an uncaught exception prints its stack trace and exits with 1, **overriding** any `process.exitCode` set earlier. - **A handler that returns:** the process keeps running; when it finally exits it uses `process.exitCode`, which means 0 if nothing set it. A crashed service can therefore report success. - **A handler that throws:** Node does not recurse into it; it prints the new stack and exits with 7. - **`--unhandled-rejections=warn-with-error-code`:** an unhandled rejection with no listener sets `process.exitCode` to 1 and the process keeps running. - **`process.exit(n)`:** exits with `n`, beating a previously set `process.exitCode`. - **Implicit codes yield to explicit ones:** Node's docs show that `process.exitCode = 9` before an unsettled top-level `await` produces 9, not 13. ## Reading code 13 Code 13 surprises people because nothing threw. In an ES module, top-level `await` suspends the module until its promise settles. If that promise never settles, for example a `new Promise(() => {})` or an `await` on an event that is never emitted, and nothing else keeps the loop alive, the loop drains with the module unfinished. Node treats a module that never finished evaluating as a failure and exits with 13. The fix is in the code: settle the promise, or keep a real handle open, such as a listening server, if the wait is intended. ## Signals: the 128 + N codes When a process dies from a fatal signal, POSIX practice reports 128 plus the signal number: `SIGABRT` (6) gives 134, `SIGKILL` (9) gives 137, `SIGTERM` (15) gives 143. In Node specifically, `SIGTERM` and `SIGINT` have default handlers on non-Windows platforms that exit with `128 + signal number`; installing a listener for either removes that default, so the process no longer exits on its own and the code becomes whatever your handler chooses. How container runtimes report these codes is covered with Docker's lifecycle material. ## Making exit codes useful - **Never let a handler turn a crash into 0.** An `'uncaughtException'` listener should set `process.exitCode = 1` or exit non-zero, or a supervisor counts the crash as a clean stop. - **Give your own failures distinct codes.** Use `process.exitCode` with values that do not collide with the codes Node documents, so 7 or 13 keep their meaning in alerts. - **Treat 7 as two bugs.** The original error and the faulty handler both need fixing, and the stack printed last belongs to the handler. - **Check 9 after a runtime upgrade.** An option a script relied on that a newer `node` no longer accepts fails at start-up with 9 before any of your code runs.

  • Why might a Node.js service that clearly crashed report exit code 0?
    An `'uncaughtException'` listener cancelled the default crash and never set a code. The process kept running in an unknown state, and when it eventually exited, for example after its server closed, it used `process.exitCode`, which was unset, so the status was 0. The fix is a handler that always exits non-zero.
  • Which wins in Node.js: a process.exitCode you set, or the code Node would choose itself?
    For implicit codes such as 13, the unsettled top-level `await`, your explicit `process.exitCode` wins, as the Node docs demonstrate. The uncaught-exception crash is the documented exception: with no handler it exits with 1 and overrides any `process.exitCode` set earlier. An explicit `process.exit(n)` exits with `n` whatever `process.exitCode` holds.

  • Exit code 1 always means the code called process.exit(1).
  • Exit code 7 means the process ran out of memory.
  • A process that exits 0 cannot have hit an uncaught exception.
  • Exit code 13 means the script has a syntax error.
  • A process.exitCode set earlier survives an unhandled crash.