How to Handle Graceful Shutdown in Node.js: Best Practices

To handle a graceful shutdown in Node.js, listen for termination signals like SIGINT or SIGTERM and close your server and resources inside those handlers. This ensures your app finishes ongoing requests and cleans up before exiting.

Why This Happens

When you stop a Node.js app abruptly (like pressing Ctrl+C), the server may close immediately without finishing current requests or cleaning resources. This can cause data loss, corrupted files, or open connections.

javascript

const http = require('http');

const server = http.createServer((req, res) => {
  res.end('Hello World');
});

server.listen(3000);

// No shutdown handling
console.log('Server running on port 3000');

Output

Server runs but stops immediately on Ctrl+C without cleanup

The Fix

Listen for SIGINT and SIGTERM signals to detect when the app should stop. Inside these handlers, close the server and any other resources like database connections. Then exit the process after cleanup.

javascript

const http = require('http');

const server = http.createServer((req, res) => {
  res.end('Hello World');
});

server.listen(3000, () => {
  console.log('Server running on port 3000');
});

function gracefulShutdown() {
  console.log('Received shutdown signal, closing server...');
  server.close(() => {
    console.log('Server closed. Exiting process.');
    process.exit(0);
  });
  // If server doesn't close in 10 seconds, force exit
  setTimeout(() => {
    console.error('Forcing shutdown');
    process.exit(1);
  }, 10000);
}

process.on('SIGINT', gracefulShutdown);
process.on('SIGTERM', gracefulShutdown);

Output

Server running on port 3000
Received shutdown signal, closing server...
Server closed. Exiting process.

Prevention

Always add signal handlers for SIGINT and SIGTERM in your Node.js apps to cleanly close servers and resources. Use server.close() to stop accepting new requests but finish ongoing ones. Set a timeout to force exit if cleanup hangs.

Use linting rules or code reviews to ensure graceful shutdown is implemented. Test shutdown behavior regularly to avoid surprises in production.

Related Errors

Developers may see errors like ECONNRESET or UnhandledPromiseRejectionWarning if shutdown is abrupt. These happen when connections close unexpectedly or async cleanup fails.

Fix these by properly awaiting async cleanup tasks and closing connections before exiting.

Key Takeaways

Always listen for SIGINT and SIGTERM signals to trigger graceful shutdown.

Use server.close() to stop new requests and finish ongoing ones before exit.

Clean up all resources like database connections inside shutdown handlers.

Set a timeout to force exit if cleanup takes too long.

Test shutdown behavior to avoid unexpected crashes or data loss.