Tomcat keepalive and connectionTimeout: coordinating timers with your reverse proxy

When Tomcat sits behind nginx, HAProxy, Apache httpd, or a cloud load balancer, the proxy-to-Tomcat connection is almost always persistent keep-alive. Both ends maintain idle-timeout timers that independently decide when to close. If those timers are not coordinated, the proxy periodically tries to reuse a connection Tomcat has already closed, and the user gets a 502 or a connection reset.

The proxy and Tomcat each behave correctly on their own. The problem is a race between two independently configured clocks, and both sets of defaults are tuned for direct client-to-server traffic, not proxy-to-origin. The one rule that eliminates the race: the inner layer (Tomcat) must always time out after the outer layer (the proxy).

What it is and why it matters

You run Tomcat behind a proxy that pools persistent connections. Intermittently, users see 502 Bad Gateway, “connection reset by peer”, or sporadic latency spikes that do not correlate with CPU, heap, or thread pool pressure. The errors cluster at a regular interval, often around the keepalive idle timeout, and vanish if you disable keep-alive between proxy and Tomcat.

If that matches, the root cause is a timer mismatch, not a Tomcat performance problem. The JVM looks healthy. The thread pool has headroom. Tomcat’s access log shows the request never arrived. The only evidence is on the proxy side.

This matters more now because nginx 1.29.7 (March 2026) reportedly made HTTP/1.1 with keep-alive to upstreams the default. Operators who previously had HTTP/1.0 with Connection: close between nginx and Tomcat now have persistent connections whether they configured them or not. Timer coordination matters more after that change than before.

How it works

Tomcat exposes three connector attributes that govern connection lifetime. They are independent and apply at different points in the connection lifecycle.

connectionTimeout governs how long Tomcat waits, after accepting a TCP connection, for the client to send the request line. The documented default is 60000ms (60 seconds); the standard server.xml shipped with Tomcat overrides this to 20000ms (20 seconds). A value of -1 disables the timeout entirely. This timer protects against Slowloris-style attacks where a client opens a connection and never sends a complete request.

keepAliveTimeout governs how long Tomcat waits, after finishing one request, for the next request to arrive on the same persistent connection. If unset, it defaults to connectionTimeout. A value of -1 disables it. This is the timer that matters most behind a reverse proxy: it controls how long idle pooled connections live.

maxKeepAliveRequests governs how many HTTP requests Tomcat will pipeline on a single connection before closing it unconditionally. Default is 100. A value of -1 allows unlimited requests. A value of 1 disables keep-alive entirely. Behind a busy proxy with a large connection pool, this counter can force connection churn even when the idle timeout would not.

The race is a two-clock problem. Both the proxy and Tomcat maintain their own idle timers for the same TCP connection. If Tomcat’s keepAliveTimeout fires first, Tomcat sends a FIN and the socket enters the kernel’s close path. If the proxy’s timer has not yet fired, the proxy still believes the connection is reusable. On the next request, the proxy writes to the stale socket. Depending on timing, it gets an EOF, a TCP RST, or the request lands on a freshly reopened socket. The proxy surfaces this as a 502.

The rule that eliminates the race: the inner layer (Tomcat) must always time out after the outer layer (the proxy). The proxy should be the one to close idle connections, because the proxy is the one that tracks which connections it intends to reuse.

sequenceDiagram
    participant C as Client
    participant P as Reverse Proxy
    participant T as Tomcat
    C->>P: HTTP request
    P->>T: Forward on pooled keep-alive conn
    T->>P: HTTP response
    Note over P,T: Connection goes idle
    Note over T: keepAliveTimeout fires first
    T-->>P: TCP FIN, Tomcat closes
    Note over P: Proxy still caches the socket
    C->>P: Next request arrives
    P->>T: Write to stale socket
    T-->>P: TCP RST or EOF
    P-->>C: 502 Bad Gateway

Where it shows up in production

The mismatch surfaces differently depending on which proxy you use and how aggressively it pools connections.

nginx. nginx’s client-facing keepalive_timeout defaults to 65s. The upstream keepalive idle timeout is documented at 75s in the upstream module. Before nginx 1.29.7, HTTP/1.0 was the default to upstreams, so each request got a fresh connection and the race did not arise. With 1.29.7, HTTP/1.1 and keep-alive to upstreams are now default. The keepalive directive in the upstream block (the number of idle connections to keep per worker) must still be set explicitly; without it, nginx will not pool upstream connections even with HTTP/1.1. If you upgrade nginx and suddenly see 502s against a Tomcat that was stable before, this is the first thing to check. The fix is to set Tomcat’s keepAliveTimeout higher than nginx’s upstream idle timeout, typically by 10 to 30 seconds.

HAProxy. HAProxy reuses server connections when option http-keep-alive is active. The timeout http-keep-alive directive controls how long HAProxy holds an idle persistent connection open. The same inner-longer-than-outer rule applies: Tomcat’s keepAliveTimeout must exceed HAProxy’s keep-alive timeout.

Apache httpd mod_proxy. mod_proxy maintains a connection pool per child process. The ttl parameter on the ProxyPass directive controls the keepalive idle timeout for pooled backend connections. If Tomcat closes a pooled connection before httpd expects it, the next request to that backend fails and httpd returns 502.

Cloud Foundry gorouter. The gorouter’s keep-alive timeout to backend instances is 90 seconds and is not changeable by application configuration. Tomcat deployed on Cloud Foundry must have keepAliveTimeout set above 90s (commonly 100s or 120s) to avoid the race. This is a known issue for platforms that wrap Tomcat in a fixed-configuration router.

Embedded Tomcat (Spring Boot). Spring Boot exposes server.tomcat.keep-alive-timeout and server.tomcat.max-keep-alive-requests as application properties. Some embedded Tomcat setups defaulted keepAliveTimeout to as little as 2000ms, which made the race trivially reproducible behind any proxy with a longer idle timeout.

Tradeoffs and when to use it

The naive fix is to disable keep-alive between the proxy and Tomcat by setting maxKeepAliveRequests=1. This eliminates the race entirely but imposes a TCP handshake (and TLS handshake, if applicable) on every request. At high request rates this measurably increases CPU on both the proxy and Tomcat and adds latency. Disabling keep-alive is a valid diagnostic step and a valid choice for very low-traffic services, but it is not the right production answer for most workloads.

The correct approach is to tune the timers so the proxy always closes first, and to size maxKeepAliveRequests so that connection churn from the request counter does not undermine the idle timeout.

Setting keepAliveTimeout. Make it longer than the proxy’s upstream idle timeout by a comfortable margin. Rule of thumb: proxy timeout plus 10 to 30 seconds. If nginx’s upstream idle timeout is 60s, set Tomcat’s keepAliveTimeout to 75s or 90s. If you are behind a router with a fixed timeout you cannot change (gorouter at 90s), set Tomcat above that.

Setting connectionTimeout. This can stay lower than keepAliveTimeout. connectionTimeout protects against clients that connect and never send a request. Behind a proxy, the proxy always sends a request promptly, so a shorter connectionTimeout (20s, the server.xml default) is safe and desirable. There is no requirement that connectionTimeout match keepAliveTimeout.

Setting maxKeepAliveRequests. Behind a proxy with a long-lived pool, the default of 100 can cause Tomcat to close connections after the counter exhausts even if the idle timer has not fired. This produces the same 502 race if the proxy does not expect the close. Set it to -1 (unlimited) when the proxy is trusted to manage connection lifetime, or set it high enough (1000 or more) that the counter is not the dominant lifecycle mechanism.

What you give up by lengthening keepAliveTimeout. Idle keep-alive connections consume a poller slot and a file descriptor on Tomcat. With NIO, they do not consume a worker thread. A proxy maintaining a pool of 64 idle connections costs Tomcat 64 file descriptors and 64 poller registrations. This is cheap relative to the cost of reconnecting per request, but it is not free. If your proxy opens a very large pool and your FD limit is low, the tradeoff shifts. Keep FD usage below 50% of the ulimit in normal operation, with production ulimits at 65535 or higher.

Signals to watch in production

Signal	Why it matters	Warning sign
Proxy-side 502 rate or “connection reset” in proxy error log	Primary symptom of the race	Spikes at a regular interval matching the keepAliveTimeout
Tomcat `connectionCount` (JMX: `Catalina:type=ThreadPool,name="http-nio-8080"`)	Shows how many pooled connections Tomcat is holding	Sustained high count that does not track request rate indicates proxy keepalive pool, not user load
Tomcat file descriptor count (JMX: `java.lang:type=OperatingSystem` -> `OpenFileDescriptorCount`)	Idle keep-alive connections consume FDs	Steady upward drift unrelated to request throughput
Tomcat `currentThreadsBusy` vs `maxThreads`	Confirms whether 502s are thread exhaustion or timer race	If busy threads are low and 502s still occur, the problem is the timer race, not capacity
nginx upstream error log (“upstream prematurely closed connection”)	nginx’s own signal that Tomcat closed first	Correlates with the race window
Access log `%D` for affected requests	Confirms whether requests that 502’d ever reached Tomcat	No corresponding Tomcat access log entry for the 502’d request

Behind a proxy, Tomcat’s connectionCount reflects the proxy’s keepalive pool, not the end-user count. A single nginx worker maintaining 32 keep-alive connections shows as 32 on Tomcat even if there is one active user. This is normal and expected, but it means connection count is not a direct measure of user load when a proxy is in front.

How Netdata helps

Correlate the proxy’s 502 rate with Tomcat’s connectionCount and currentThreadsBusy on the same per-second timeline. A 502 spike with flat thread utilization points to the timer race; a 502 spike with threads pinned at max points to thread exhaustion.
Track Tomcat file descriptor count against the configured ulimit. Per-second granularity catches FD drift from a misbehaving proxy pool before it becomes a hard failure.
Monitor keepAliveCount alongside connectionCount to distinguish idle pooled connections from active request-bearing connections. A rising idle count with flat request rate confirms the proxy is holding connections open.
Watch GC pause time alongside connection metrics. A long GC pause can cause the proxy to time out on an otherwise healthy connection, producing a 502 that looks like the keepalive race but has a different root cause.
Alert on nginx upstream error patterns and correlate them with Tomcat connector metrics in a single view to confirm the inner-closed-first hypothesis without switching between tools.