Production and Reliability
16. How do you shut down a Node.js server gracefully?
On SIGTERM, stop accepting connections, let in-flight requests finish, cancel outbound work, close pools, and exit before the orchestrator's grace period runs out (30 seconds by default in Kubernetes).
const shutdown = new AbortController();
process.once('SIGTERM', () => {
shutdown.abort(); // cancel in-flight outbound calls
server.close(async () => { // runs when open requests finish
await pool.end();
process.exit(0);
});
server.closeIdleConnections(); // drop idle keep-alive sockets now
setTimeout(() => { // hard deadline
server.closeAllConnections();
process.exit(1);
}, 25_000).unref();
});
Keep-alive is the detail most answers miss: server.close() waits for every open connection, and idle keep-alive sockets can hold it open.
Since Node.js 19, close() drops idle connections itself, and closeIdleConnections() and closeAllConnections() (added in 18.2) handle the rest; see the http docs.
The readiness probe should also start failing first, so the load balancer stops sending traffic.
17. How do you carry a request ID through every log line without passing it everywhere?
With AsyncLocalStorage from node:async_hooks. A value set with run() at the start of a request is readable from any function that request awaits, and concurrent requests keep separate values:
import { AsyncLocalStorage } from 'node:async_hooks';
const requestContext = new AsyncLocalStorage();
app.use((req, res, next) => {
requestContext.run({ requestId: req.get('x-request-id') ?? randomUUID() }, next);
});
function log(msg) {
const ctx = requestContext.getStore();
console.log(JSON.stringify({ requestId: ctx?.requestId, msg }));
}
The async_context docs recommend it over building on the raw async_hooks API. Node.js 24 switched its implementation to AsyncContextFrame by default, which the release notes describe as more efficient.
Tracing libraries such as OpenTelemetry use the same mechanism to keep the active span.
18. How do you cancel async work, for example an outbound call when the client disconnects?
Pass an AbortSignal. fetch, timers, streams, fs/promises and events.once all accept one. AbortSignal.timeout(ms) creates a deadline, and AbortSignal.any(), available since 20.3, aborts when the first of several signals fires:
async function getStock(sku, requestSignal) {
const signal = AbortSignal.any([
requestSignal, // client went away
shutdown.signal, // server is stopping
AbortSignal.timeout(2_000), // our own deadline
]);
const res = await fetch(`${INVENTORY_URL}/stock/${sku}`, { signal });
return res.json();
}
A timeout rejects with a TimeoutError, and a manual abort with an AbortError, so callers can tell the two apart. This matters for fetch in particular, because undici's defaults allow 300 seconds each for headers and body.
The composition methods are listed in the globals reference.
19. How should a service handle an uncaught exception?
Log it and exit. The process docs call 'uncaughtException' "a crude mechanism" meant as a last resort, because after an unexpected throw the application is in an undefined state.
A supervisor, whether Kubernetes, systemd or a process manager, restarts the process.
The distinction to draw is between operational errors (a timeout, a 404 from a partner API, invalid input), which code expects and handles, and programmer errors (reading a property of undefined), which mean the code is wrong.
Wrapping low-level errors with new Error('charge failed', { cause: err }) keeps the original stack for the logs while giving callers a meaningful message.
20. Node.js is single-threaded. Can it still have race conditions?
Yes, whenever a read and a write are separated by an await. Other requests run during the wait and act on the same stale value:
async function withdraw(accountId, amount) {
const { balance } = await db.getAccount(accountId); // read
if (balance >= amount) {
await db.setBalance(accountId, balance - amount); // write from a stale read
}
}
// Two concurrent withdraw(80) calls on a balance of 100 both succeed.
In a local simulation of this code, two concurrent withdrawals of 80 from 100 left a balance of 20: both passed the check.
The fix moves the check into one atomic operation (UPDATE accounts SET balance = balance - $1 WHERE id = $2 AND balance >= $1), a transaction with a row lock, or a distributed lock when the resource is not in a database.
An in-process mutex only works while the service runs as a single instance.
21. How do you scale a Node.js API across CPU cores and machines?
Run more processes. Inside one machine, the cluster module forks workers that share a port; the primary distributes connections round-robin on every platform except Windows, according to the cluster docs.
In containers, most teams skip cluster and run one process per container with a CPU limit of about one core, letting the orchestrator add replicas.
Scaling out only works if the process is stateless: sessions, rate-limit counters and caches that must be shared live in Redis or the database.
WebSockets add a second requirement, a pub/sub layer so a message published on one instance reaches clients connected to another.