Node.js Keep-Alive Timeouts Behind a Load Balancer: How We Stop Random 502s in NestJS
Table of Contents
About the Author

Ahmed Mahmoud
Author & Developer
Software engineer passionate about web development and user experience design.
Founder of Devya · eng-ahmed.com ↗Headline: Random 502 responses from an AWS Application Load Balancer or Nginx in front of a healthy Node.js server usually come from one default: http.Server.keepAliveTimeout is 5 seconds, shorter than the proxy's 60-second idle timeout. At Devya we set the Node.js keep-alive timeout above the proxy's idle timeout, and we apply the same rule in reverse to outbound fetch calls.
The bug report always reads the same way: a small share of requests fail with 502, there is no pattern by endpoint, and the application logs show nothing. The logs are empty because the request never reached our code. These notes cover why that happens, the one line that fixes it in NestJS, and the mirror-image problem on outbound calls.
Key takeaways
- Node.js closes idle connections after 5 seconds: server.keepAliveTimeout defaults to 5000 ms on http.Server.
- Proxies wait much longer: an AWS Application Load Balancer keeps idle connections for 60 seconds by default, and so does an Nginx upstream keep-alive pool.
- The rule for every hop: the side that sends requests must give up on an idle connection before the side that receives them does.
- The NestJS fix is one line: app.getHttpServer().keepAliveTimeout = 65_000 on the Express adapter; Fastify already defaults to 72 seconds.
- Outbound calls have the same race: Node.js fetch pools connections, and reusing a socket the remote server already closed fails with ECONNRESET.
Why does a load balancer return random 502s in front of a healthy Node.js server?
A load balancer returns a random 502 when it reuses an idle keep-alive connection at the same moment Node.js closes it. HTTP keep-alive, the HTTP/1.1 behavior of reusing one TCP connection for many requests, lets the load balancer hold a pool of open connections to each backend. Node.js closes any connection that has been idle for keepAliveTimeout, which is 5 seconds by default. The load balancer still considers that connection usable for up to 60 seconds.
The race needs only a few milliseconds. The load balancer writes a request onto the connection while the Node.js close is still in flight. Node.js answers with a TCP reset, the load balancer has no response to forward, and the client gets a 502 Bad Gateway. The handler never ran, so the NestJS logs stay clean. Low-traffic services hit this more often than busy ones, because their connections sit idle long enough to reach the 5-second mark.
What are the default keep-alive timeouts in Node.js, AWS ALB, and Nginx?
The defaults disagree, and the receiving side is almost always the shorter one. We checked the Node.js values on a current runtime with http.createServer(): keepAliveTimeout is 5000, headersTimeout is 60000, and requestTimeout is 300000.
- AWS ALB to Node.js: the ALB idle timeout is 60 seconds and the Node.js keepAliveTimeout is 5 seconds. We set Node.js to 65 seconds.
- Nginx upstream pool to Node.js: the upstream keepalive_timeout is 60 seconds and the Node.js keepAliveTimeout is 5 seconds. We set Node.js to 65 seconds.
- Google Cloud Application Load Balancer to backend: the backend keep-alive timeout is fixed at 600 seconds. We set Node.js to 620 seconds.
- Node.js fetch to another API: undici keeps idle connections for 4 seconds by default. The client value must stay below the remote server's value.
Node.js also advertises its timeout. Every keep-alive response carries a Keep-Alive: timeout=5 header, but AWS ALB and Nginx do not adjust their upstream pools based on that header. Newer Node.js releases add server.keepAliveTimeoutBuffer, 1000 ms by default, which keeps the socket open slightly longer than the advertised value. A 1-second buffer helps clients that honor the header; it does not close a 55-second gap.
How do we set keepAliveTimeout in NestJS?
In NestJS on the default Express adapter, we set keepAliveTimeout on the underlying http.Server returned by app.getHttpServer(). The value must be greater than the load balancer's idle timeout, so we use 65 seconds for an ALB left at its 60-second default.
In main.ts, after NestFactory.create(AppModule), we call const server = app.getHttpServer() and assign server.keepAliveTimeout = 65_000 before app.listen().
The NestJS Fastify adapter needs no change for a 60-second proxy, because Fastify sets keepAliveTimeout to 72 seconds by default. For a longer proxy timeout we pass the option to the adapter: new FastifyAdapter({ keepAliveTimeout: 620_000 }).
We keep the number in one environment variable next to the load balancer configuration, because the two values are only correct relative to each other. Raising the ALB idle timeout to 120 seconds without touching Node.js brings the 502s back.
Does Nginx need the same fix?
Nginx needs the same fix only when upstream keep-alive is enabled. Without a keepalive directive in the upstream block, Nginx opens a new connection to Node.js for every request, so there is no idle connection to race on. With the pool enabled, which also requires proxy_http_version 1.1 and an empty Connection header, Nginx keeps idle upstream connections for 60 seconds by default.
When Node.js wins the race against Nginx, the Nginx error log says: upstream prematurely closed connection while reading response header from upstream. We either raise the Node.js keepAliveTimeout above 60 seconds or lower the upstream keepalive_timeout below the Node.js value. Both satisfy the rule; we prefer raising Node.js so the pool stays warm.
Why do outbound fetch calls from Node.js fail with ECONNRESET?
Outbound fetch calls fail with ECONNRESET when a Node.js process reuses a pooled connection that the remote server has already closed. On outbound calls our service is the sender, so the roles flip: our client's idle timeout must be shorter than the remote server's. Node.js fetch runs on undici, the HTTP client bundled with Node.js, and undici keeps idle connections for 4 seconds by default. The legacy http.globalAgent has had keepAlive: true since Node.js 19, with a 5-second idle timeout.
undici reads the Keep-Alive: timeout=N response header and holds the connection for roughly that long, capped by keepAliveMaxTimeout. A server that advertises a long timeout but sits behind a proxy with a shorter one produces stale sockets. With fetch the failure surfaces as TypeError: fetch failed with a socket error as the cause.
We cap the hint with an undici Agent: setGlobalDispatcher(new Agent({ keepAliveTimeout: 4_000, keepAliveMaxTimeout: 30_000 })). We also retry on connection reset, but only for idempotent requests such as GET and PUT. A POST that died on a reset socket may or may not have reached the remote handler, so we retry a POST only when the request carries an idempotency key.
How do we confirm keep-alive timeouts are the cause?
We confirm the cause by matching three signals before changing anything. First, the 502s have no matching entry in the application logs. Second, ALB access logs show elb_status_code 502 with a target_status_code of -, meaning the target never produced a response. Third, curl -v straight to the Node.js port shows Keep-Alive: timeout=5, proving the default is still in place.
After the fix we read server.keepAliveTimeout once at startup and log it next to the configured proxy timeout. We do not quote a before-and-after error rate here, because the rate depends entirely on traffic shape; the signal we look for is the unexplained 502s with empty target status dropping to zero.
FAQ
Q: What value should we use for keepAliveTimeout behind an AWS ALB?
A: Use a value above the ALB idle timeout. For the default 60-second idle timeout, server.keepAliveTimeout = 65_000 is enough.
Q: Do we still need to set headersTimeout above keepAliveTimeout?
A: That advice worked around a bug in older Node.js releases. On current Node.js, headersTimeout defaults to 60000 ms and limits how long a client may take to send request headers, so we leave it at the default.
Q: Does disabling keep-alive fix the 502s?
A: Disabling keep-alive removes the race, but every request then pays for a new TCP connection, and a new TLS handshake where TLS is used. Raising keepAliveTimeout fixes the 502s and keeps connection reuse.
Q: Does keepAliveTimeout matter on Vercel or other serverless platforms?
A: The inbound side does not, because the platform owns the HTTP server and the proxy in front of it. The setting matters when a team runs its own Node.js process in Docker, on a VM, or on Kubernetes. The outbound fetch side applies everywhere.
Further Reading
Backend Engineering
Streaming Large CSV Exports from Postgres in Node.js and NestJS: Backpressure, pipeline(), and the Connection a Slow Download Holds
A CSV export that loads every row into memory works in staging and fails in production. Here is how our team streams exports from Postgres with pg-query-stream and pipeline() in NestJS, how backpressure keeps memory flat, and the costs streaming adds: errors after the first byte, a held database connection, proxy buffering, and CSV injection.
Backend Engineering
Postgres Advisory Locks in Node.js and NestJS: How We Run Cron Jobs on Exactly One Replica
When a NestJS API scales to two replicas, every @Cron job runs twice. We use a Postgres advisory lock, not Redis, to keep scheduled jobs on one replica: the pg_try_advisory_xact_lock pattern we use with node-postgres, why session-level locks break behind PgBouncer, Neon, and Supabase poolers, and where fencing tokens still matter.