Diagnosing and Resolving Disconnected Bamboo Build Agents

The Problem: The 'Unavailable' Agent

When a Bamboo build agent enters a 'Disconnected' or 'Unavailable' state, build queues stall and deployment pipelines fail. This usually happens because the agent process has crashed, the network path is blocked, or the agent's Java Virtual Machine (JVM) is no longer responding to the server's heartbeat requests.

Quick Diagnostic Matrix

Symptom	Likely Cause	Primary Log Indicator
Agent disappears suddenly during a heavy build	JVM Heap Exhaustion	java.lang.OutOfMemoryError
Agent fails to connect after server update	JRE Version Mismatch	java.io.InvalidClassException
Intermittent disconnection/reconnection	Network Timeout/Firewall	Connection reset by peer
Agent won't start or stays 'Offline'	Disk Space Exhaustion	No space left on device
Authentication failures on startup	System Clock Drift	Invalid token or Timestamp expired

Step-by-Step Recovery Process

Perform these checks in order. Do not restart the Bamboo server until you have verified the agent-side logs, as a server restart will not fix client-side resource issues.

1. Verify Network Path and Port

The agent must be able to reach the Bamboo server on its configured port (usually 54663 for remote agents). Run this from the agent machine using a terminal with network utilities installed:

# Replace [server-hostname] and [port] with your actual configuration
nc -zv [server-hostname] [port]

Expected Result: A "Succeeded" or "Connected" message. If the connection times out, check for firewall rules or VPN drops between the agent subnet and the server.

2. Inspect Agent Logs for JVM Crashes

Navigate to the agent's installation directory and examine agent.log and bamboo-agent.log. Search specifically for memory-related failures.

• Finding: OutOfMemoryError: Java heap space.
• Fix: Increase the heap size in the wrapper.conf file (for wrapped agents) or the startup script.

Configuration Example: To increase the heap to 4GB, locate the wrapper.java.maxmemory setting:

# In wrapper.conf
wrapper.java.maxmemory=4096

Risk: Ensure the physical RAM on the agent machine exceeds this value. Setting the heap too high can trigger OS-level swapping, which severely degrades build performance.

3. Validate JRE Consistency

Bamboo requires the agent to run on a Java version compatible with the server. If the server was recently upgraded, the agent may fail to deserialize data sent by the server.

Run the following on both the server and agent to compare versions:

java -version

If versions differ significantly (e.g., Java 8 vs Java 11), update the agent's JRE to match the server's supported version.

4. Check Working Directory Disk Space

Agents download build plans and store artifacts locally. If the disk is full, the agent cannot write its status file and will stop reporting to the server.

# Run on the agent machine to check available space
df -h

If the partition containing the bamboo-agent/xml or working directory is at 100%, clear old build artifacts or expand the volume.

5. Synchronize System Clocks

Bamboo uses time-sensitive tokens for authentication. If the agent's system clock drifts more than a few minutes from the server's clock, the server will reject the heartbeat.

Verify the current time on both machines. If they differ, ensure both are syncing via NTP (Network Time Protocol).

Verification and Rollback

To verify the fix, navigate to Administration > Build Agents in the Bamboo console. The agent should move from 'Disconnected' to 'Online' with a current heartbeat timestamp.

Rollback: If you modified wrapper.conf to increase memory and the agent fails to start (due to insufficient physical RAM), revert the wrapper.java.maxmemory value to its previous setting and restart the agent service.

Escalation Criteria

If the agent remains disconnected after these steps, escalation to your Infrastructure or Network team is warranted if:

• nc (netcat) shows the port is closed despite firewall rules being open.
• The agent logs show Connection refused immediately upon startup, suggesting the server-side listener is down.
• The agent crashes with a Segmentation Fault, indicating a deeper JVM or OS incompatibility.