criticalIntermediateUSE#agent#node#offline#remoting

Jenkins agent node offline - remoting handshake failure

Jenkins agent shows 'Offline' in the node management page

Likely source:availabilityconnectivity

Focused incident mode — strips away everything but this runbook.

Symptoms

  • Jenkins agent shows 'Offline' in the node management page
  • Builds stuck in queue with 'Waiting for next available executor on <agent>'
  • Agent log shows 'GO AWAY' or 'remoting mismatch' error

Always update the agent.jar on the agent host after upgrading Jenkins master. Remoting version mismatch is the most common cause of the 'GO AWAY' error.

Evidence to grab

Collect these artifacts before you change anything — they prove (or rule out) each cause.

  • Agent node status

    curl -s -u <USER>:<TOKEN> <JENKINS_URL>/api/json?tree=computer[name,offline,offlineCauseReason]

  • Agent remoting log

    ssh <AGENT_HOST> tail -100 ~/.jenkins/logs/remoting.log

Diagnostic flow

Run the steps in order, marking each claim confirmed or refuted. The evidence you gather feeds the ranked causes below.

Guided decision tree is ready.

Steps with commands, expected output, and pass/fail branches.

Ranked root causes

Evidence checklist

  • Log shows 'GO AWAY' or 'remoting version mismatch'
  • Jenkins was upgraded but the agent JNLP jar was not updated

Confirm before fixing

curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/agent/<AGENT_NAME>/api/json?tree=version'
READ

Check the agent's reported remoting version

Fix

curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/jnlpJars/agent.jar' -o agent.jar && ssh <AGENT_HOST> java -jar agent.jar -url <JENKINS_URL> -secret @secret.key -name <AGENT_NAME>
CHANGE

Download and relaunch the agent with the matching agent.jar

Resolution runbook

Apply from top to bottom after the cause is confirmed. Review every command before running it — risk tags are shown on each.

1
curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/computer/<AGENT_NAME>/api/json?tree=offline,offlineCause'
READ

Check the agent status

2
ssh <AGENT_HOST> tail -100 ~/.jenkins/logs/remoting.log
READ

Read the agent logs

3
curl -s -u <USER>:<TOKEN> '<JENKINS_URL>/jnlpJars/agent.jar' -o /tmp/agent.jar
READ

Download the latest agent.jar

4
ssh <AGENT_HOST> nohup java -jar agent.jar -url <JENKINS_URL> -secret @secret.key -name <AGENT_NAME> > /dev/null 2>&1 &
CHANGE

Restart the agent with the updated jar

Prevention

  • Upgrade agents in a rolling fashion after each Jenkins master upgrade.
  • Monitor agent online status and alert when agents go offline.
  • Use Jenkins' built-in agent management API to automate agent health checks.
  • Pin the Jenkins and agent versions to avoid unexpected incompatibilities.

Related runbooks

Same stack, same failure family — worth a skim.

Jenkins build stuck in queue - no available executorhigh

Build stuck in queue with 'Waiting for next available executor'

JenkinsFoundationUSE2 causes
Open runbook
Jenkins workspace locked - concurrent build conflicthigh

Build fails with 'Workspace is locked by another build'

JenkinsFoundation2 causes
Open runbook

Commands marked READ CHANGE DESTRUCTIVE — never run DESTRUCTIVE commands against production data you cannot restore. Copy → verify → execute.