Diagnosing Bamboo Elastic Agent Registration Failures in Bamboo 9.x

Recognizable condition

In the Bamboo UI elastic agents appear as Offline or never transition to Online. The agent log (typically atlassian-bamboo-agent.log) contains messages such as Failed to register with Bamboo server, Connection timed out, or Version mismatch.

Cause / diagnostic table

Symptom	Likely cause
Agent logs show connection timeout or refused	Network connectivity blocked (firewall, security group, NACL)
Log contains Version mismatch or Unsupported agent version	Agent version does not match Bamboo server version
Log reports Not authorized to perform elasticbamboo:* or similar	Missing or insufficient AWS IAM permissions for the elastic agent role
Agent start‑up fails with Unable to allocate Elastic IP	AWS account has exhausted its Elastic IP address limit
Agents stay offline despite network and permissions being OK	Bamboo server overloaded (high CPU, memory, DB connection exhaustion)

Ordered checks

1. Test network reachability – From the agent host (EC2 instance or on‑prem VM) run:

   # Replace  with the base URL of your Bamboo server, e.g. https://bamboo.example.com
   curl -I '/agentServer/'

   or, if the agent uses a raw TCP port (default 8085):

   telnet '' 8085

   Required permission: shell access to the agent host. Risk: none; the command only probes connectivity.
2. Check agent version warnings – Examine atlassian-bamboo-agent.log for lines containing Version mismatch or Unsupported. Example grep:

   grep -i "version mismatch" "$AGENT_LOG/atlassian-bamboo-agent.log"

   Required permission: read access to the agent log directory.
3. Validate IAM role permissions – In the AWS console, locate the IAM role attached to the elastic agent’s EC2 instance or launch template. Ensure the policy includes:

   {
     "Effect": "Allow",
     "Action": ["elasticbamboo:*"],
     "Resource": "*"
   }

   Required permission: IAM read (or admin) to view policies.
4. Confirm Elastic IP availability – Run:

   aws ec2 describe-addresses --query 'Addresses[].PublicIp' --output text | wc -l

   Compare the count to the account limit (default 5 per region). If the limit is reached, you will see allocation failures in the agent log. Required permission: ec2:DescribeAddresses.
5. Review Bamboo server health – On the Bamboo server host, check:
   • CPU usage: top or CloudWatch metric CPUUtilization
   • Memory usage: free -m or CloudWatch MemoryUtilization
   • Database connections: SHOW PROCESSLIST; on the underlying DB or Bamboo’s atlassian-bamboo.log for Connection pool exhausted messages.
   Required permission: SSH access to the Bamboo server (or appropriate CloudWatch read).

Fixes tied to findings

• Network block – Adjust the security group or network ACL attached to the agent subnet to allow inbound TCP traffic on the Bamboo agent port (default 8085) from the agent’s IP/security group, and outbound TCP from the agent to the Bamboo server on the same port. After changing, re‑run the connectivity test from step 1.
• Version mismatch – Match the elastic agent version to the Bamboo server version. For Bamboo 9.x, download the corresponding agent installer from https://www.atlassian.com/software/bamboo/download and replace the agent binary, then restart the agent service. Test in a staging environment first if possible.
• Insufficient IAM permissions – Attach or update the IAM policy for the agent’s role to include the elasticbamboo:* action (as shown in the check). Follow the principle of least privilege: limit the resource ARN if you know the specific Elastic IP or stack resources.
• Exhausted Elastic IP pool – Release unused Elastic IPs via the AWS console or CLI:

  aws ec2 release-address --allocation-id eipalloc-XXXXXXXX

  If you need more addresses, request a limit increase through AWS Support. After freeing an IP, restart the agent; it should acquire a new address and register.
• Bamboo server overload – If CPU > 80 % or memory pressure is observed, consider:
  • Restarting the Bamboo service (systemctl restart bamboo on Linux)
  • Scaling up the instance type or adding nodes in a cluster
  • Increasing the database connection pool size in bamboo.cfg.xml (e.g., hibernate.max_pool_size=50).
  After the server stabilizes, re‑run the agent connectivity test.

Escalation criteria

If after completing all checks and applying the relevant fix(es) the agent remains offline for more than 30 minutes, or if multiple elastic agents fail to register simultaneously, open a support ticket with Atlassian. Include:

• Agent logs (atlassian-bamboo-agent.log) from the affected hosts
• Bamboo server logs (atlassian-bamboo.log) covering the same time window
• Relevant AWS CloudTrail events for elasticbamboo actions and EC2 address allocations
• Output of the connectivity test (step 1) and IAM policy JSON

Verification and practical check

1. After a fix, refresh the Bamboo UI → Agents tab; the agent should show Online within two minutes.
2. Run a simple test plan (e.g., a plan that checks out a repository and runs echo hello) using the newly online elastic agent. Confirm the plan completes successfully.
3. Inspect atlassian-bamboo.log on the Bamboo server for the absence of registration error messages (Failed to register, Connection timed out) after the agent comes online.

Limitations

This guide covers the most common causes of registration failure in Bamboo 9.x elastic agents. Issues specific to custom plugins, proxy authentication, or TLS certificate problems are not addressed here and may require additional investigation.