Connection: keep-alive and the Keep-Alive header (tested)

In HTTP/1.1 every connection is persistent by default: after a response, the TCP socket stays open for the next request unless one side sends Connection: close. Connection: keep-alive mostly matters for HTTP/1.0. Keep-Alive: timeout=5 is only a hint about how long the server will keep an idle socket. We measured what Node.js, curl and Python actually send, how many connections they open, when an idle socket really closes, and how to reproduce the ECONNRESET you get when a client reuses a socket the server is closing.

1. What Node.js sends by default

A plain http.createServer((req, res) => res.end('ok\n')) on Node.js 24.21.0, requested with curl:

HTTP/1.1 200 OK
Date: Fri, 02 Oct 2026 02:07:38 GMT
Connection: keep-alive
Keep-Alive: timeout=5
Content-Length: 3

When the request had Connection: close (curl -H "Connection: close") or was HTTP/1.0 (curl --http1.0), the response said Connection: close, had no Keep-Alive header, and the server closed the socket right after it. The server's defaults, read from the server object:

2. When an idle socket really closes

We sent one request over a raw TCP socket, then timed how long it took the server to close the idle connection:

Node.js advertises keepAliveTimeout but waits an extra keepAliveTimeoutBuffer (1 s) before it closes. That gives clients a margin. Two traps: a value under 1000 ms is rounded down to timeout=0 in the header, and keepAliveTimeout = 0 turns idle closing off entirely.

headersTimeout is a different thing. It limits how long a client can take to send the request headers. With http.createServer({ headersTimeout: 3000, connectionsCheckingInterval: 500 }), a client that sent half a request got HTTP/1.1 408 Request Timeout after 3,008 ms. With the defaults (60 s, checked every 30 s by default), a half-sent request was still open after 8 s, as expected. For limits on header size, see HTTP header size limits.

3. Which clients reuse connections

Each client made 5 sequential requests to the same Node.js server. We counted new TCP connections with server.on('connection'):

What this means:

• Reuse lives inside one process and one connection pool. Five curl commands always open five connections, whatever the headers say. curl -v prints Re-using existing http: connection with host 127.0.0.1 for the second and later URLs in one command.
• requests.get() sends Connection: keep-alive but creates and discards a new pool on every call, so nothing is reused. Use a requests.Session().
• In Node.js 24, http.globalAgent.keepAlive is true (options: keepAlive: true, scheduling: 'lifo', timeout: 5000). A new http.Agent() you create yourself still defaults to keepAlive: false.
• fetch() back-to-back opened a second socket because the first was not yet back in the pool. With 50 ms between requests, 4 of 5 used the same socket.

4. How long each client keeps an idle socket

We sent a request, waited, then sent another, against the default Node.js server (Keep-Alive: timeout=5, real close at 6 s) unless noted:

So fetch and agents with a timeout read the Keep-Alive: timeout=N hint and drop the socket early. A keep-alive agent without timeout ignored the hint and kept the socket until the server's FIN arrived. Against a server sending timeout=0, fetch and the keep-alive agent opened a new connection for every request, even 100 ms apart.

5. Reproducing the ECONNRESET race

This is the classic keep-alive bug: the client sends a request on a pooled socket at the same moment the server closes it. The server resets the connection and the client gets ECONNRESET or "socket hang up". We set the server to keepAliveTimeout = 2000 and keepAliveTimeoutBuffer = 0, used new http.Agent({ keepAlive: true }), and waited 1,985 to 2,015 ms (1 ms steps) between two requests:

With the default 1 s buffer the window just moved to 2,997 to 3,001 ms (5 resets in 31 tries). The buffer only helps clients that read the hint, and this agent did not. The same sweep with new http.Agent({ keepAlive: true, timeout: 1500 }) gave 21 of 21 new connections and no errors. Rare in a test, but at thousands of requests per second with the right idle gaps, it shows up as occasional 502s or resets.

The fix is always the same: the client must give up an idle socket before the server does.

• Node.js clients: give custom agents a timeout, for example new http.Agent({ keepAlive: true, timeout: 30000 }). Measured above: it then follows the server's hint.
• Node.js behind a load balancer or proxy: the proxy is the client. Set server.keepAliveTimeout longer than the proxy's idle timeout. From the docs, not measured: the AWS Application Load Balancer idle timeout defaults to 60 s, so a common setting is server.keepAliveTimeout = 65000. Older advice is to set headersTimeout above keepAliveTimeout too.
• From the docs, not measured: nginx keepalive_timeout defaults to 75 s for clients. For upstream keep-alive, nginx needs keepalive in the upstream block, proxy_http_version 1.1; and proxy_set_header Connection "";, and its keepalive_timeout there (default 60 s) should be shorter than your app's.
• Retry idempotent requests (GET, PUT, DELETE) once on ECONNRESET.

6. HTTP/2 and HTTP/3 forbid these headers

RFC 9113 says HTTP/2 must not use connection-specific headers (Connection, Keep-Alive, Transfer-Encoding, Upgrade, Proxy-Connection). One connection carries many streams, so there is nothing to keep alive per request. In Node.js 24.21.0 http2:

• stream.respond({ ':status': 200, connection: 'keep-alive' }) threw ERR_HTTP2_INVALID_CONNECTION_HEADERS: HTTP/1 Connection specific headers are forbidden: "connection". The same happened with keep-alive and on the client side with session.request().
• The compatibility API res.setHeader('Connection', 'keep-alive') did not throw. It printed UnsupportedWarning: The provided connection header is not valid, the value will be dropped, and the response had no such header.
• curl --http2-prior-knowledge -H "Connection: keep-alive" still shows the header in the -v output, but it is not in the HTTP/2 frames curl logs, and the server did not receive it.

If a tool shows Connection: keep-alive on an HTTP/2 response, it is showing HTTP/1.1 headers or making them up. Related: Transfer-Encoding: chunked vs Content-Length, which is also gone in HTTP/2.

7. Checklist

1. Check the response: curl -sI http://host/ shows Connection and Keep-Alive. curl -v url1 url2 shows whether the second request said Re-using existing.
2. In Python use a requests.Session(). In Node.js use the global agent, fetch, or an agent with keepAlive: true and a timeout.
3. Make every client idle timeout shorter than the server's: browser and app to load balancer, load balancer to app.
4. Leave the Node.js keepAliveTimeout above 1000 ms so the header is not timeout=0, and never 0 on a public server.
5. Do not set Connection or Keep-Alive on HTTP/2 responses.

Written with AI assistance. Measured on 2026-10-02 with Node.js 24.21.0 (http.createServer and http2 on localhost:8987-8988, built-in fetch, http.Agent), curl 8.14.1, Python 3.13.5 with requests 2.32.3 and urllib. We counted connections with the server's 'connection' event and timed idle closes with a raw TCP client. nginx and cloud load balancer timeouts are quoted from their documentation, not measured. PlainHeaders is our extension; Node.js, curl and Python are free.