httpServer.keepAliveTimeout default of 5s is too low, causes subtle long-connection failures

[yujiang]

---

Description

I'd like to share a real production experience and suggest a change to the default value of httpServer.keepAliveTimeout.

It took us over a year to diagnose a network issue caused by this silent but critical default.

---

The Problem

Node.js sets the default http.Server.keepAliveTimeout to 5000ms (5s).
However, this is far shorter than the default expectations in:

• browsers (usually 60s),
• reverse proxies like Nginx,
• and mobile HTTP stacks (such as WeChat Mini Game client).

This led to:

• Unexpected disconnections between HTTP keep-alive requests;
• Difficult-to-reproduce API failures and silent drops;
• No error logs on server or client — making diagnosis extremely hard.

---

Our Debugging Journey

1. Suspected Nginx misconfiguration.
2. Suspected WeChat client or its proxy.
3. Suspected Wi-Fi/mobile network instability.
4. Finally, one of our developers asked an AI assistant, which identified the root cause instantly.

This issue cost us significant time and frustration.

---

Reproduction Example

const http = require('http');

const server = http.createServer((req, res) => {
  setTimeout(() => {
    res.end('hello');
  }, 6000); // response delayed beyond keepAliveTimeout
});

server.listen(8080);

With default settings, the server will close the connection before responding.

---

Workaround

server.keepAliveTimeout = 60000; // Set to 60s explicitly

---

Suggestion

• Increase the default to 60s (industry standard);
• Or at least log a warning when using the default 5s value;
• Or improve documentation to highlight this sharp edge.

---

Why It Matters

Silent timeouts cause real-world pain and are extremely hard to detect.
Most developers don't know to check keepAliveTimeout, especially when using frameworks like Express or behind proxies.

Changing this one default would prevent countless hours of misdiagnosis.

Thanks for your amazing work on Node.js! 🙏