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.
process.on('SIGTERM', () => console.log('asked to stop'));
Try it
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.
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
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 withcloseAllConnections()orcloseIdleConnections()and a timeout that callsprocess.exit().- Containers: the main process of a Docker container receives
SIGTERMondocker stop, followed bySIGKILLafter the grace period (10 seconds by default). Starting your app through a shell wrapper can swallow the signal; useexecor a direct command. - Windows: only
SIGINT,SIGBREAK,SIGHUP(closing the console window) andSIGTERM(limited) exist;process.kill()with them terminates unconditionally. Ctrl+C works in real terminals only. SIGPIPEis ignored by Node by default; broken pipes show up asEPIPEerrors 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.