// 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
Share

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

  1. FIX 1Update agent.jar

    1. 01Download <jenkins URL>/jnlpJars/agent.jar onto the agent
    2. 02Compare with md5sum to the controller's copy
    3. 03Restart the agent with the new jar
    Did this fix it?
  2. FIX 2Check the inbound port

    1. 01Run curl -I <jenkins URL>/tcpSlaveAgentListener/ from the agent
    2. 02Confirm the TCP port for inbound agents in Manage Jenkins > Security is open in firewalls and load balancers
    3. 03Or switch to WebSocket connection in the agent configuration
    Did this fix it?
  3. FIX 3Match the Java version

    1. 01Agents must run at least the Java version the controller requires (Java 21+ on current releases)
    2. 02Upgrade Java on the agent and reconnect
    Did this fix it?
  4. FIX 4Run the agent as a service

    1. 01On Linux use a systemd unit, on Windows wrap it with WinSW so it restarts automatically
    2. 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 us

Watch Jenkins Get an email when its price changes, it has an outage, or we publish a new fix. No spam.

Fixed it? Share this guide

The same problem in other apps

All not loading, error messages & connection guides →

Other Jenkins errors

All 14 Jenkins errors and fixes →