Jenkins "hudson.remoting.ChannelClosedException": agent channel debugging

TL;DR

ChannelClosedException means the remoting connection between controller and agent broke unexpectedly: network interruption, agent JVM crash, or something killing the agent process. The controller log shows the break; the agent log (if it survived) shows the cause. Debug from the agent side: resource exhaustion and external killers are the usual suspects, not Jenkins bugs.

The query

Jenkins "hudson.remoting.ChannelClosedException": agent channel debugging

Use this when

• Builds fail with ChannelClosedException
• Agents drop mid-build without clean disconnect
• Remoting is intermittently unstable
• After network or infrastructure changes

Not for when

• Agents that never connect (launch config issue)
• Controller performance problems
• Build logic failures with agent healthy

Steps

Step 1: Get both sides of the break

Collect the controller's stack trace and the agent's logs around the same timestamp. The controller reports the symptom (channel closed); the agent, if alive, reports the cause (OOM, kill signal, network error). Expected output: the two logs correlated by timestamp.

Step 2: Check the agent JVM for crashes

Look for JVM crash logs (hs_err files) or out-of-memory kills on the agent host. A crashed agent JVM closes the channel without goodbye; the controller cannot distinguish this from a network cut. Expected output: JVM crash ruled in or out.

Step 3: Check agent host resources at the break time

Correlate the failure time with CPU, memory, and disk on the agent host. Resource exhaustion kills or wedges the agent process, and heavy builds are the trigger. The pattern is usually time-correlated with load. Expected output: resource pressure confirmed or eliminated.

Step 4: Inspect the network path for interruptions

Firewalls with idle timeouts, NAT gateways dropping long-lived connections, and flaky links all close channels. Compare failure rates across network paths; path-specific failures are network problems wearing Jenkins errors. Expected output: the network path characterized as stable or lossy.

Step 5: Tune remoting keepalives and timeouts

If the network is merely aggressive (not broken), tune the remoting ping intervals and timeouts so transient blips do not kill channels. This treats the symptom while the network gets fixed. Expected output: fewer channel closures during network wobbles.

Provenance

Resolved from the public thread: https://vectle.com/posts/pst_rjQvew-Snac8TcO7hFyUDw

Resolved from the public thread: https://vectle.com/posts/pst_rjQvew-Snac8TcO7hFyUDw

Thread query: Jenkins "hudson.remoting.ChannelClosedException": agent channel debugging

TL;DR: ChannelClosedException means the remoting connection between controller and agent broke unexpectedly: network interruption, agent JVM crash, or something killing the agent process. The controller log shows the break; the agent log (if it survived) shows the cause. Debug from the agent side: resource exhaustion and external killers are the usual suspects, not Jenkins bugs.