Diagnosing Bamboo Remote Agent Disconnections and 'Agent Unavailable' States

A Bamboo remote agent that shows as Offline or Unavailable in the Agents administration page stops your build queue cold. The good news: the failure almost always falls into one of five buckets — network reachability, agent JVM memory, JRE mismatch, disk saturation, or leftover processes from a previous run. This guide walks through how to tell them apart and what to do for each.

Version assumption: behavior described here applies to Bamboo 8.x/9.x remote agents communicating with the server over the agent broker port (default 54663). Confirm your port in Administration → Agents → Agent communication, since it is configurable.

Recognizing the condition

Typical symptoms:

• Agent listed as Offline in Administration → Agents even though the agent machine is up.
• Builds stuck in the queue with "no agent can build this job" style messages.
• Agent repeatedly flapping between Online and Offline.
• On the agent host, the wrapper or agent process is running but no builds are picked up.

Cause and diagnostic quick reference

Ordered checks

1. Confirm what the server sees

In the Bamboo web UI, open Administration → Agents and check the agent's status and last-seen time. An agent that heartbeated recently but is disabled is a different problem (someone or a capability check disabled it) than one that has not heartbeated in hours.

2. Read the agent log first, not the server log

On the agent machine, open <bamboo-agent-home>/logs/atlassian-bamboo-agent.log. Search for Connection refused, heartbeat, OutOfMemoryError, and serialization exceptions. The first repeating error after the last successful heartbeat is usually your cause.

3. Test network reachability from the agent host

From a shell on the agent machine (no special privileges needed), test the broker path to the server:

nc -zv bamboo-server.example.com 54663

Replace the hostname and port with your actual server address and broker port. A succeeded/open result means TCP reachability is fine and you should look elsewhere; a timeout or refusal points at firewalls, security groups, or the server-side broker listener. Coordinate any firewall change with your security team — opening ports can affect other services.

4. Check memory and disk on the agent host

Run (Linux, unprivileged):

df -h /path/to/bamboo-agent-home
free -m
dmesg | grep -i "killed process" | tail

A full agent-home filesystem prevents checkouts and state writes; an OOM-killed Java process explains a dead agent with no graceful shutdown in the log. If you raise the agent heap via wrapper.conf (wrapper.java.maxmemory) or the JAVA_OPTS used by your agent launcher, make sure the host has physical RAM headroom — an oversized heap that forces OS swapping will make builds slower, not more stable.

5. Verify the Java version

On the agent host, check what the agent actually runs with:

java -version

Compare it against the Java version your Bamboo server version supports (check the supported platforms page for your Bamboo release). A mismatch — for example an agent launched with an old JRE after a server upgrade — commonly surfaces as handshake or serialization errors right after an upgrade. If your service manager launches the agent, verify the JAVA_HOME in the service or wrapper configuration, not just your interactive shell.

6. Look for zombie processes

If the agent fails to restart or builds hang at checkout, list leftover processes:

ps aux | grep -E 'bamboo|java'
lsof +D /path/to/bamboo-agent-home/xml-data/build-dir 2>/dev/null | head

Kill stale build processes (you may need sudo if they ran under another user), then restart the agent. Killing processes is destructive to any in-flight work, so confirm they are genuinely orphaned first.

Fixes tied to findings

• Network: open the broker port inbound on the server and outbound on the agent side; confirm with the nc test again after the change.
• Memory: clear disk pressure or raise heap modestly within physical RAM; restart the agent and watch the log for a clean registration.
• JRE mismatch: point the agent at a supported JDK and restart.
• Disk full: prune old build directories under the agent's build-dir; Bamboo can also clean these automatically if configured.
• Zombies: kill orphaned processes, then restart the agent service.

Verifying the fix

After any change, confirm three things: the agent shows Online in Administration → Agents; the agent log shows successful registration/heartbeat lines after restart; and a queued build actually starts on that agent. Note that restarting the Bamboo server alone does not repair a misconfigured or broken remote agent — the fix lives on the agent side in most cases.

When to escalate

Escalate to Atlassian support or your platform team when: the agent registers but drops within minutes despite clean logs (possible broker/TLS issue); multiple agents fail simultaneously after a server upgrade (version compatibility problem); or you see broker errors on the server side in atlassian-bamboo.log that persist after agent-side fixes. Include the agent log excerpt, Bamboo version, and Java versions on both ends in the ticket.