Diagnosing Bamboo Build Agent 'Disconnected' Status: A Practical Guide

Recognizable Condition

When a Bamboo remote build agent flips to Disconnected in the administration console, builds stop dispatching to that agent and queue behind remaining capacity. The useful takeaway is that most disconnects stem from one of five conditions: a blocked network path, an incompatible Java runtime, a full working directory, a stale agent configuration, or JVM memory exhaustion. Work through the checks below in order; each step produces a specific signal that points to a targeted fix.

The affected agent appears under Agents in the Bamboo administration console with a red or grey status and a stale heartbeat timestamp. New builds do not start on that agent. If the agent process is running but the server UI still shows Disconnected, treat it as a connectivity or authentication problem rather than a crashed process.

Cause and Diagnostic Signals

Cause	Diagnostic signal	Primary location
Network or firewall block	Connection refused or timeout	bamboo-agent.log; nc/telnet test
Incompatible JRE	Startup crash or unsupported class version error	Agent log; java -version output
Insufficient disk space	Agent shutdown or initialization failure	Agent working directory; df output
Invalid configuration	Authentication failed or handshake error	bamboo-agent.properties
Memory exhaustion	Agent hangs; OutOfMemoryError in log	bamboo-agent.log; JVM settings

Ordered Checks

These steps assume a standard Bamboo server with a remote agent installed on a separate host. Exact paths, default ports, and supported Java versions vary by Bamboo release and installation method; verify against the documentation for your specific version.

1. Confirm the Agent State and Logs

On the Bamboo server, open the Agents tab in the administration console and note the status and last heartbeat. On the agent machine, inspect the log file in the agent home directory (commonly named bamboo-agent.log). Look for Connection refused, Authentication failed, or OutOfMemoryError.

# Run on the agent machine
tail -n 100 /path/to/agent/home/bamboo-agent.log

2. Verify Network Reachability

From the agent machine, test the TCP path to the Bamboo server's agent communication port. Replace <bamboo-server-host> and <agent-port> with your actual values.

# Run on the agent machine
nc -vz <bamboo-server-host> <agent-port>
# or
telnet <bamboo-server-host> <agent-port>

A successful connection means the network path is open. A timeout or refusal indicates a firewall rule, security group, or server listener problem.

3. Check the Java Runtime Environment

Remote agents require a JRE supported by your Bamboo server release. On the agent machine, run:

# Run on the agent machine
java -version

Compare the output against the Java version required by your Bamboo version. A mismatch can cause startup crashes or protocol incompatibilities.

4. Inspect Disk Space on the Agent Working Directory

Agents need free space for source checkouts and build artifacts. On the agent machine, check the filesystem holding the working directory:

# Run on the agent machine
df -h /path/to/agent/working/directory

If the volume is full or nearly full, the agent may shut down or refuse new builds.

5. Review Agent Configuration

Open bamboo-agent.properties in the agent home directory. Confirm the server URL matches the reachable Bamboo server address and that any security token is current. The following is an illustrative structure only:

# Example content; exact property names vary by Bamboo version
server=http://bamboo.example.com:8085/agentServer/
securityToken=YOUR_TOKEN_HERE

Changes to this file do not apply while the agent is running.

6. Look for Memory Exhaustion

If the agent process is alive but unresponsive, search the agent log for OutOfMemoryError. Memory exhaustion can drop connections without producing an explicit error in the server UI.

Fixes Tied to Findings

• Network test fails: Coordinate with network or security administrators to allow the required TCP port between the agent host and the Bamboo server. Restrict the rule to the specific server IP where possible. Risk: overly broad exposure of the agent communication port.
• Wrong JRE: Install the supported Java version and restart the agent service. Ensure the agent wrapper points to the correct Java binary. Requires administrative rights on the agent host. Risk: other applications on the host may depend on the existing JRE.
• Disk full: Free space or relocate the agent working directory to a volume with adequate capacity, then restart the agent. Requires filesystem permissions. Risk: deleting build artifacts may remove evidence needed for debugging.
• Stale configuration: Correct the server URL or security token. Stop the agent, apply the change, and start it again. If the change does not resolve the issue, revert to the previous value before further troubleshooting. Risk: an incorrect token or URL will keep the agent offline.
• OutOfMemoryError: Increase the agent JVM heap size in the wrapper configuration, but only up to the physical RAM available. Over-allocating heap without corresponding RAM can cause OS-level swapping and severe performance degradation. Restart the agent after the change.

Escalation Criteria

Escalate to your Bamboo administrator or Atlassian support if:

• All network, JRE, disk, configuration, and memory checks pass but the agent still shows Disconnected.
• Server-side logs show broker or messaging errors unrelated to the agent host.
• The disconnect began immediately after a Bamboo server version upgrade.

Limitations and Verification

This guide covers common remote-agent failure modes. It does not address containerized agents, elastic agents, or Bamboo Data Center clustering specifics. Because exact file paths, default ports, and supported Java versions depend on your Bamboo release, verify against version-specific documentation for your deployment.

To confirm a fix, return to the Agents tab in the Bamboo administration console and verify the agent shows as online with a recent heartbeat. Dispatch a test plan or trigger a build to confirm the agent accepts and executes work.