Why Won't Node.js Containers Shut Down Cleanly? (feat. Graceful Shutdown)

TL;DR AI
2 min readKey summary
A Node.js container had a graceful shutdown issue where it did not stop on termination signals and eventually reached SIGKILL.
The root cause was identified as Linux PID 1 signal-handling behavior plus lingering async work in the Node.js event loop.
The fix was to run dumb-init as PID 1 and add timeouts to NestJS shutdown hooks.
Kubernetes terminationGracePeriodSeconds was also increased to give the process enough time to exit cleanly.
