Skip to content
Tutorials Center
My learning

Topics

Node.js Reference ยท process

Node.js process signal events

Reference for signal events in Node.js: handling SIGINT and SIGTERM for graceful shutdown, which signals cannot be caught, and Windows differences.

Operating systems use signals to tell a process that something happened or that it should stop. Node.js turns them into events on process: add a listener named after the signal, such as 'SIGINT' or 'SIGTERM', and your function runs instead of the default action (which is to end the program).

The classic use is a graceful shutdown: when a container orchestrator sends SIGTERM, or a user presses Ctrl+C (SIGINT), you stop accepting work, finish what is running, and then exit.

NODE
process.on('SIGTERM', () => console.log('asked to stop'));

Try it

Node.js Catching a signal sent to ourselves

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Node.js Graceful shutdown of a server

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

Syntax

NODE
process.on(signalName, (signal, number) => { })
Signal Typical meaning Default action
SIGINT Interrupt, Ctrl+C in a terminal Exit (code 130 in shells)
SIGTERM Polite request to terminate Exit
SIGHUP Terminal closed, or "reload config" by convention Exit
SIGUSR1 Starts the inspector in Node; reserved Start debugger
SIGUSR2 Free for your own use Exit
SIGWINCH Terminal size changed Ignored
SIGBREAK Ctrl+Break (Windows) Exit
SIGKILL, SIGSTOP Forced kill and pause Cannot be caught
Name Description
signal The signal name, such as 'SIGTERM'.
number The numeric value of that signal on this platform.

Returns: listener return values are ignored.

Errors / edge cases: registering a listener for SIGKILL or SIGSTOP throws an error (uv_signal_start EINVAL). SIGBUS, SIGFPE, SIGSEGV and SIGILL should not be handled in JavaScript, because they come from corrupted state.

Usage notes

  • Adding a listener removes the default action. If your handler does not exit, Ctrl+C no longer stops the program. Always arrange for the process to end eventually, and offer a second Ctrl+C that forces it.
  • Use process.once() for shutdown handlers, so a second signal falls back to the default behaviour or your forced-exit path.
  • server.close() stops new connections but waits for open ones. Keep-alive connections can delay it, so combine it with closeAllConnections() or closeIdleConnections() and a timeout that calls process.exit().
  • Containers: the main process of a Docker container receives SIGTERM on docker stop, followed by SIGKILL after the grace period (10 seconds by default). Starting your app through a shell wrapper can swallow the signal; use exec or a direct command.
  • Windows: only SIGINT, SIGBREAK, SIGHUP (closing the console window) and SIGTERM (limited) exist; process.kill() with them terminates unconditionally. Ctrl+C works in real terminals only.
  • SIGPIPE is ignored by Node by default; broken pipes show up as EPIPE errors on streams.
  • Library code should not install signal handlers. The application decides how to shut down.
  • Worker threads do not receive signals; only the main thread can listen.