npx skills add jasnell/node-skills --skill node-process-timeoutSKILL.md
--process-timeout
| Feature | Versions | Stability | Flag |
|---|---|---|---|
--process-timeout=duration (exit code 124) |
v26.11.0 (not on v24) | 1.1 Active development | itself |
--report-on-process-timeout |
v26.11.0 | 1.1 | needs --process-timeout |
subprocess.timedOut, error.timedOut (exec/execFile callback) |
v27.0.0-alpha.0.1.0 (YAML); absent in v26.13.0 | 2 | none |
Experimental API. Before relying on these details, run the
node-experimental-checkskill's probe (ornode --versionplus a feature-detect one-liner) and check the docs for the installed version:https://nodejs.org/docs/<version>/api/<module>.html. If the installed version disagrees with this skill, the installed version wins.
Make CI fail instead of hang
node --process-timeout=10m server-smoke.js # units: ms s m h, positive integer
node --process-timeout=15m --test # caps the whole run
node --process-timeout=5m --report-on-process-timeout --report-directory=reports app.js
When it fires, the process exits with 124 (like timeout(1), overriding
process.exitCode). It prints the JS stack if the main thread was running JS,
otherwise the handles keeping the loop alive:
(node:25418) Process timed out after 5s (--process-timeout). Exiting with code 124.
Main thread was not executing JavaScript.
Resources keeping the event loop alive:
TCPServerWrap (listening on [::]:3000, fd 20)
Timeout x2 (next due in 2931ms)
Find what keeps the process alive
Run it with a short timeout and read the resource list (TCPServerWrap,
Timeout, ProcessWrap (pid N), PipeWrap…). The report's header.trigger
is 'ProcessTimeout', and its libuv array lists every handle.
Child processes and node --test
fork()children (and any child givenprocess.execArgv) inherit the flag and time out on their own clock, measured from their own start.spawn(process.execPath, …)withoutexecArgvdoes not inherit it.fork(file, { execArgv: [] })opts a child out.- Children are not killed when the parent times out. They outlive it and stop only through their own timeout.
node --testpasses the flag to each test-file process. The runner's clock starts first, so the runner usually fires first and lists the hung file only asProcessWrap (pid N). The orphaned file process then exits on its own timeout.
Pitfalls
- It is not allowed in
NODE_OPTIONS(exit 9). Put it on the command line or in the npm script. - It can't be combined with
--inspect*,node inspect,--runor--build-snapshot.inspector.open()throwsERR_INSPECTOR_NOT_AVAILABLE. 'exit'/'beforeExit'handlers don't run. Coverage (NODE_V8_COVERAGE) and--cpu-profoutput are still written.- A main thread blocked in native code (
execSync) gets 2 s to respond, then the process exits 124 with a "did not respond" note and no stack. subprocess.timedOutbelongs to thetimeoutoption of spawn/exec/execFile/fork, not to this flag. For sync APIs, checkerr.code === 'ETIMEDOUT'.
Don't
- Don't wrap the command in
timeout 600 node …or writesetTimeout(() => process.exit(1), …).unref()watchdogs. On 26.11+ the flag gives the same exit code plus a diagnosis. - Don't install
why-is-node-runningorwtfnodejust to list open handles.--process-timeoutprints them. - Don't use
--test-timeoutfor "the run never ends". It is per test, and tests that pass but leak a handle still hang.
Reference
- rules/behavior.md — read for the exact output formats, error messages, exit codes, the report, and verified child-process/test-runner timing.