// troubleshooting guide · jenkins
Jenkins Agent Went Offline During the Build
- Status
- Workaround available
- platforms:
- Jenkins agents (Linux, Windows, macOS, Kubernetes)
- updated:
- November 16, 2026
- reports:
- 4
- Method
- how we research
RUNBOOK · jenkins/agent-offline4 FIXES
// quick answer
The connection between controller and agent dropped. Check network timeouts, make sure agent.jar matches the controller version after upgrades, give the agent enough resources and run it as an auto-restarting service.
Most likely fix: Update agent.jar
How to fix it
// try these in order, the most common fix is first
FIX 1Update agent.jar
- 01Download <jenkins URL>/jnlpJars/agent.jar onto the agent
- 02Compare with md5sum to the controller's copy
- 03Restart the agent with the new jar
Did this fix it?FIX 2Check the inbound port
- 01Run curl -I <jenkins URL>/tcpSlaveAgentListener/ from the agent
- 02Confirm the TCP port for inbound agents in Manage Jenkins > Security is open in firewalls and load balancers
- 03Or switch to WebSocket connection in the agent configuration
Did this fix it?FIX 3Match the Java version
- 01Agents must run at least the Java version the controller requires (Java 21+ on current releases)
- 02Upgrade Java on the agent and reconnect
Did this fix it?FIX 4Run the agent as a service
- 01On Linux use a systemd unit, on Windows wrap it with WinSW so it restarts automatically
- 02Check the agent machine's memory and disk so it isn't killed mid-build
Did this fix it?
SANDBOX · jenkins RUNS IN YOUR BROWSER
Try it: push, review, run CI and merge in a code host and cloud workspace
A hands-on Jenkins-style sandbox, including the spots where users get stuck. See where problems like this one start. 1-2 minutes, nothing is saved.
Symptoms
Builds fail with 'Agent went offline during the build', 'Connection was broken', ClosedChannelException or EOFException; agents show as disconnected in Manage Jenkins > Nodes.
Why it happens
- C-01Network timeouts or firewalls closing idle connections (half-closed TCP)
- C-02Outdated agent.jar after upgrading the controller
- C-03Agent Java version below the controller's minimum
- C-04Agent machine out of memory or rebooted
- C-05Inbound (TCP) agent port blocked or misconfigured
// this guide also covers
- jenkins agent went offline during the build
- jenkins agent disconnects
- jenkins connection was broken
- jenkins agent offline
Still not working?
If Jenkins keeps failing, you're not alone. See every Jenkins problem users report or the alternatives people switch to.
Have an app idea? Our small team builds any software: web and mobile apps, games, desktop, AI tools. Price agreed together.
Talk to usThe same problem in other apps
Other Jenkins errors
- Jenkins Build Stuck 'Waiting for Next Available Executor'
- Jenkins Build Stuck and Won't Abort
- Jenkins Plugins Failed to Load After Update
- Jenkins Not Starting: 'Job for jenkins.service failed'
- Jenkins java.lang.OutOfMemoryError: Java Heap Space
- Why Is Jenkins So Slow?
- Jenkins 'Scripts Not Permitted to Use Method' Error
- Jenkins GitHub Webhook Not Triggering Build