Keep-Alive & Connection Limits

Tune HTTP keep-alive and connection timeouts so Node servers behave correctly behind nginx, ALB, and other reverse proxies.

Recipe

Quick-reference recipe card - copy-paste ready.

import { createServer } from "node:http";
 
const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "text/plain", Connection: "keep-alive" });
  res.end("ok\n");
});
 
// Align with your reverse proxy (nginx default keepalive_timeout is 75s)
server.keepAliveTimeout = 65_000;   // slightly below proxy timeout
server.headersTimeout = 66_000;     // must exceed keepAliveTimeout
server.requestTimeout = 30_000;
server.maxConnections = 1000;       // cap concurrent sockets
 
server.listen(3000);

When to reach for this: Intermittent 502 errors during deploys, connection reset logs, or EMFILE (too many open files) under load.

Working Example

import { createServer } from "node:http";
import { Agent, request as httpRequest } from "node:http";
 
// --- Server tuning ---
const server = createServer((req, res) => {
  res.writeHead(200, { "Content-Type": "application/json" });
  res.end(JSON.stringify({ ok: true }));
});
 
server.keepAliveTimeout = 65_000;
server.headersTimeout = 66_000;
server.requestTimeout = 30_000;
server.listen(3000);
 
// --- Outbound client with connection reuse ---
const agent = new Agent({
  keepAlive: true,
  maxSockets: 50,        // per-host concurrent connections
  maxFreeSockets: 10,    // idle sockets kept in pool
  timeout: 30_000,
});
 
export function callDownstream(path: string): Promise<string> {
  return new Promise((resolve, reject) => {
    const req = httpRequest(
      { hostname: "api.internal", port: 8080, path, agent, timeout: 10_000 },
      (res) => {
        const chunks: Buffer[] = [];
        res.on("data", (c) => chunks.push(c));
        res.on("end", () => resolve(Buffer.concat(chunks).toString()));
      }
    );
    req.on("error", reject);
    req.on("timeout", () => { req.destroy(); reject(new Error("timeout")); });
    req.end();
  });
}

What this demonstrates:

• Server-side keep-alive timeout aligned below the proxy
• headersTimeout greater than keepAliveTimeout (Node requirement)
• Outbound Agent with keepAlive: true for connection pooling
• Per-request timeout on outbound calls

Deep Dive

How It Works

• HTTP/1.1 defaults to persistent connections (keep-alive)
• After a response, the TCP socket stays open for reuse
• If server and proxy disagree on when to close, one side sends data on a closed socket (RST)
• Node's keepAliveTimeout controls how long an idle server socket waits for the next request

Proxy Alignment Table

TypeScript Notes

// Log when connections approach limits
server.on("connection", (socket) => {
  socket.setTimeout(30_000);
  socket.on("timeout", () => socket.destroy());
});

Gotchas

• 502 during rolling deploys - proxy sends request to a socket Node already closed. Fix: set keepAliveTimeout 5-10s below proxy timeout.
• headersTimeout too low - Node 18+ destroys connections mid-headers. Fix: headersTimeout > keepAliveTimeout.
• No outbound Agent - every HTTP call opens a new TCP connection. Fix: reuse a module-level Agent with keepAlive: true.
• maxSockets default (Infinity) - one slow downstream can exhaust file descriptors. Fix: cap maxSockets per host.
• Ignoring server.maxConnections - under attack or viral traffic, accept queue grows unbounded. Fix: set maxConnections and handle server.on("drop").
• ULIMIT too low - default 1024 FDs is not enough for busy APIs. Fix: raise ulimit -n in container/systemd config.

Alternatives

FAQs

Related

• Reverse Proxy Awareness - X-Forwarded headers and trust proxy
• HTTP/2 & HTTP/3 Considerations - protocol termination
• HTTP Basics in Node - server fundamentals
• Performance on Express - framework-level tuning
• HTTP Fundamentals Best Practices - section checklist

Stack versions: This page was written for Node.js 24.18.0 (Active LTS), npm 10+, TypeScript 5.6+, Express 5, Fastify 5, and NestJS 11.