javax.net.ssl.SSLHandshakeException when Bamboo agent connects to server

Resolution

To resolve a javax.net.ssl.SSLHandshakeException when a Bamboo agent connects to a server via HTTPS, you must ensure the Java Runtime Environment (JRE) used by the agent trusts the server's certificate. For self-signed or expired certificates, the agent's JVM will reject the connection during the TLS handshake, preventing registration.

Option 1: Import Certificate into Global cacerts

This is the standard approach for agents sharing a common JRE. Import the server's public certificate into the default Java trust store:

keytool -importcert -alias bamboo-server -file server_cert.crt -keystore $JAVA_HOME/lib/security/cacerts

Option 2: Configure a Per-Agent Trust Store

While Bamboo does not provide a UI setting for per-agent trust stores, you can isolate trust by passing JVM arguments to the agent process via JAVA_OPTS or the agent's startup script:

• -Djavax.net.ssl.trustStore=/path/to/agent-truststore.jks
• -Djavax.net.ssl.trustStorePassword=changeit

Explanation of Behaviors

Certificate Trust

The SSLHandshakeException occurs because the agent JVM cannot verify the server's identity. If the certificate is self-signed, it is not part of the default CA bundle. If it is expired, the JVM rejects it regardless of the signer. Using a custom trust store (Option 2) is safer than modifying the global cacerts, as it prevents updates to the JRE from overwriting your changes.

DNS and IP Caching

Bamboo servers cache the resolved IP addresses of registered agents. If an agent's IP changes due to a DNS update, the server may attempt to communicate with a stale IP, causing the agent to appear offline even if the SSL handshake is successful. Since there is no dedicated admin API to flush this specific cache, the most reliable remediation is to remove and re-add the agent via the Bamboo Administration UI to force a fresh resolution.

Verification

To verify the fix and diagnose the connection, use the following scoped commands on the agent host:

• Check Certificate Validity: openssl s_client -connect <bamboo-host>:443 -servername <bamboo-host>
• Verify Trust Store Contents: keytool -list -v -keystore <path_to_truststore>
• Review Logs: Inspect atlassian-bamboo-agent.log for the full exception stack trace to confirm the handshake failure is resolved.

Diagnostic Detail Needed: Are you using a shared JRE across multiple agents on a single host, or is each agent running in an isolated container/VM? This determines whether a global cacerts modification or a JAVA_OPTS override is the appropriate path.