Diagnosing Bamboo Build Failures: JDK Not Found Error

Problem Statement

When a build plan in Atlassian Bamboo fails with the message "Unable to locate JDK - please install Java JDK", the build cannot proceed because the Bamboo agent cannot find a Java Development Kit (JDK) to compile or run Java code.

Diagnostic Table

Error	Root Cause
Unable to locate JDK - please install Java JDK	JDK path not registered in Bamboo system settings, or the agent lacks a matching JDK capability.

Ordered Checks

1. Verify Bamboo System JDK Registration
   • Navigate to Bamboo > Administration > System Settings > JDKs.
   • Confirm at least one JDK is listed and the JAVA_HOME path points to a valid JDK installation.
   • Example: /opt/jdk-17/bin/java.
2. Inspect Build Plan Requirements
   • Open the build plan and go to Plan Configuration > Requirements.
   • Check that the required JDK version matches one of the registered JDKs.
3. Check Agent Capabilities
   • Go to Administration > Agents and select the agent that ran the build.
   • Under Capabilities, ensure a JDK capability exists and the path matches the system JDK.
4. Confirm JDK Availability on Agent Machine
   • SSH into the agent host.
   • Run java -version and echo $JAVA_HOME to verify the JDK is installed and the environment variable is set.
   • Sample command:

     # Run on agent host
     java -version
     # Verify JAVA_HOME
     echo $JAVA_HOME
     

5. Review Bamboo Log for JDK Errors
   • Open /home/bamboo/logs/atlassian-bamboo.log on the Bamboo server.
   • Search for "JDK" or "Unable to locate JDK" entries.

Fixes Tied to Findings

• If no JDK is registered in system settings, add one:
  • Navigate to System Settings > JDKs.
  • Click Add JDK and provide a name and the absolute path to the JDK binary (e.g., /opt/jdk-17).
  • Save and allow Bamboo to refresh capabilities.
• If the build plan requires a different JDK version, either update the plan requirement or register the needed JDK in system settings.
• If the agent lacks a JDK capability, add it:
  • In Agents, click Edit on the agent.
  • Under Capabilities, click Add and choose JDK.
  • Set the JAVA_HOME path to the JDK installation on that host.
• After modifying capabilities, restart Bamboo if the new JDK path is not immediately recognized.

Escalation Criteria

If after completing the above checks the build still fails with the same error:

• Verify that the Bamboo server and all agents are running the same JDK major version. Mixed versions can cause capability inheritance issues.
• Check agent connectivity: ensure the agent is online and able to report capabilities to the server. Use Bamboo > Administration > Agents and confirm the agent status.
• Inspect the agent’s JAVA_HOME environment variable on the host; it must point to the JDK used for capability detection.
• As a last resort, contact Atlassian support with the log snippet and configuration details.

Verification

1. Run java -version on both the Bamboo server and each agent to confirm the JDK is available.
2. Re‑trigger the build plan and observe the status. It should transition to Success or Failed only if another error occurs.
3. Check the Bamboo log for any lingering JDK-related entries.

Limitations and Practical Checks

This guide assumes Bamboo 7.x or newer. Older versions may store JDK paths differently. Always back up configuration before making changes. Path changes require a Bamboo restart to propagate to all agents. Remote agents must have the JDK installed locally; they do not inherit the server’s JDK automatically.