skip to content

In Node.js, what happens when the process receives SIGTERM or SIGINT with no listener, and what changes once you call process.on('SIGTERM')?

level: juniorimportance: should knowfreq 52%

answer

  1. a default handler you can replace
  2. 128 plus the signal number
  3. listener removes the default exit
  4. the signal handle does not hold the loop

basics

~20 s

With no listener, Node's default handler exits at once with code 128 plus the signal number, cutting off in-flight work. Installing a listener removes that default: Node stops exiting, so the handler must drain and end the process itself.

solid answer

~40 s

On Linux and macOS, Node installs default handlers for `SIGTERM` and `SIGINT` that reset the terminal mode and exit with code `128 + signal number`: 143 for SIGTERM, 130 for SIGINT. None of your code gets to finish open requests or flush a queue. The moment you call `process.on('SIGTERM', handler)`, that default is removed: Node calls `handler('SIGTERM')` and keeps running. The listener does not hold the event loop open by itself, so the process ends only when nothing else is pending, which for a listening server means never until you close it. A handler that only logs therefore turns SIGTERM into a no-op until the platform sends `SIGKILL`, which no listener can catch.

code

javascript · 14 lines
javascript
import process from 'node:process';

let stopping = false;

function onSignal(signal) {
  if (stopping) return;
  stopping = true;
  console.log(`${signal} received, starting drain`);
  // close the server, consumers and pools here, then let the loop empty
}

// once: a second Ctrl+C finds no listener and takes Node's default exit (130)
process.once('SIGINT', onSignal);
process.once('SIGTERM', onSignal);

go deeper

for a junior

Recall the two facts: with no listener, SIGTERM and SIGINT exit at once with 128 plus the signal number, and adding a listener stops Node from exiting by itself.

for a middle

Explain why a logging-only SIGTERM handler leaves the service running until SIGKILL, and why the listener itself does not keep the loop alive.

for a senior

Show you know the drain must finish before the platform escalates to SIGKILL, and use process.once or a guard flag so repeat signals behave predictably.

for a principal

Decide the exit-code convention for a clean drain versus a forced exit, so dashboards and deploy tooling can tell the two apart across services.

## What a signal is to a Node process A **signal** is a small asynchronous notification the operating system delivers to a process. `SIGTERM` (number 15 on Linux) is the polite request to stop that service managers and deploy tooling send first. `SIGINT` (number 2) is what a terminal sends when you press Ctrl+C. `SIGKILL` (number 9) is the one that cannot be refused. Node turns signals into **events on the `process` object**: the event name is the signal's uppercase name, and a listener receives that name as its first argument. ## The default: exit immediately If no JavaScript listener is installed, Node handles `SIGTERM` and `SIGINT` itself on non-Windows platforms. The Node 24 `process` documentation describes these **default handlers** as resetting the terminal mode and then exiting with code `128 + signal number`: | Signal | Number on Linux | Exit status reported | |---|---|---| | `SIGINT` | 2 | 130 | | `SIGTERM` | 15 | 143 | | `SIGKILL` | 9 | 137 (cannot be handled) | What the default does **not** do matters most in production: - it does not stop the HTTP server accepting connections first, so requests are cut mid-response; - it does not wait for queue messages being processed, so they are redelivered or lost; - it does not close database pools, so the database sees abrupt disconnects. For a one-shot script that is fine. For a service in a rolling deploy it means every release drops whatever was in flight. ## Installing a listener removes the default The documentation is explicit: if `SIGTERM` or `SIGINT` has a listener installed, **its default behaviour is removed and Node no longer exits**. Your code now owns the whole shutdown: ```js import process from 'node:process'; process.on('SIGTERM', (signal) => { console.log(`received ${signal}`); // Node will NOT exit here on its own if a server is still listening }); ``` Two consequences follow, and both surprise people. 1. **A logging-only handler makes the service ignore SIGTERM.** The server keeps listening, the platform waits out its grace period and then sends `SIGKILL`, and the process dies with exactly the abrupt behaviour you were trying to avoid, only later. 2. **The listener does not keep the process alive.** Internally Node creates an *unreferenced* signal handle (`wrap.unref()` in `lib/internal/process/signal.js`), so a script with nothing else pending still exits normally even with a listener installed. The process stays up only because of other handles: a listening server, open sockets, timers. ## `process.on` versus `process.once` When the last listener for a signal is removed, Node closes the signal handle and the default handler applies again. So `process.once('SIGINT', shutdown)` gives a useful pattern for free: the first Ctrl+C starts a graceful drain, and a second Ctrl+C, finding no listener, takes the default path and exits at once with 130. With `process.on`, every repeat signal calls your handler again, so the handler needs a guard flag to avoid starting a second shutdown in parallel. ## Edges worth knowing - **`SIGKILL` and `SIGSTOP` cannot have listeners.** No cleanup code ever runs on `SIGKILL`, which is why the drain must finish before the platform escalates. - **Signals are not available in `worker_threads` workers**; only the main thread receives them, and it must tell its workers to stop. - **Windows** has no real POSIX signals. `SIGINT` from the console works, `SIGTERM` is documented as not supported though it can be listened on, and `process.kill()` with `SIGTERM` terminates the target unconditionally. - **Async work in the handler is fine.** The listener may start promises and return; Node keeps running because the server and sockets are still referenced, and the process exits once the drain has closed them. The handler does not need to block or call `process.exit()` to stay alive. - **The exit code becomes yours.** After a graceful drain the process exits with `process.exitCode`, which is 0 unless you set it. Some teams set it to 143 deliberately so that tooling still sees "terminated by SIGTERM"; others prefer 0 for a clean drain and a non-zero code only when a hard-exit timer fired. How the signal reaches the process in the first place, for example when Node runs as PID 1 in a container or behind a shell wrapper, is covered with container lifecycle and is a separate failure from anything Node does.

  • A small Node.js script installs a SIGTERM listener but still exits right after its work finishes. Why does the listener not keep it running?
    Node creates the signal handle unreferenced, so it never counts as pending work. The event loop stays alive only for referenced handles such as a listening server, an open socket or an active timer. A script with none of those runs to completion and exits normally; the listener would only fire if a signal arrived first.
  • During a graceful drain, a developer presses Ctrl+C a second time. What happens with process.once('SIGINT', ...) compared with process.on('SIGINT', ...)?
    With `process.once`, the listener was removed after the first signal, so Node closes the signal handle and the second SIGINT takes the default path: an immediate exit with code 130. With `process.on`, the handler runs again, so it needs a guard flag, and forcing an exit on the second signal must be coded explicitly with `process.exit()`.

  • Adding a SIGTERM listener just runs code before Node's own exit
  • Node ignores SIGTERM unless the code calls process.exit itself
  • A signal listener on its own keeps the event loop alive
  • A SIGKILL listener can flush logs before the process dies
  • Ctrl+C in a terminal sends SIGTERM to the Node process