Diagnosing Jenkins Agent Connection Failures: From Offline Status to Resolution

The Problem: The 'Offline' Agent

A Jenkins agent is marked as offline in the Manage Nodes interface, preventing jobs from scheduling. This typically manifests as a lack of heartbeats reaching the controller (master), resulting in a build queue that never clears despite available resources.

Quick Diagnostic Matrix

Use this table to map the specific error message found in your logs to the most likely root cause.

Log Message (Agent/Controller)	Likely Cause	Primary Check
Connection refused or Connection timed out	Network/Firewall Block	TCP Port Connectivity
SSLHandshakeException or PKIX path building failed	Certificate Mismatch	Java Truststore/CA
UnsupportedClassVersionError	Java Version Mismatch	java -version
Agent version mismatch or Plugin error	Outdated agent.jar	Agent JAR Timestamp

Step‑by‑Step Connection Audit

Follow these checks in order. Do not move to the next step until the current one is verified as functional.

1. Verify TCP Path Connectivity

Jenkins agents require a dedicated TCP port for communication (default is 50000). If the controller is behind a firewall or in a different subnet, this port must be open.

Run this command from the agent host (requires telnet or nc installed):

# Replace <master-host> with your controller's IP or DNS
telnet <master-host> 50000

Expected Result: The screen should clear or show "Connected". If it hangs at "Trying…", the network path is blocked by a firewall or the controller is not listening on that port.

2. Align Java Runtime Environments (JRE)

The agent must run a Java version compatible with the controller. For example, if the controller is running on Java 17, an agent running Java 8 will fail to initialize the JVM properly.

Run on both the controller and the agent:

java -version

Risk: Using different major versions (e.g., Java 11 vs Java 17) often leads to UnsupportedClassVersionError during the agent handshake.

3. Validate the agent.jar Version

When the Jenkins controller is updated, the agent.jar used by JNLP agents may become obsolete. While Jenkins often attempts to auto‑update this file, permission issues on the agent host can prevent the update.

• Check the agent's local directory for the agent.jar file.
• Compare the file timestamp with the date of the last Jenkins controller upgrade.
• Fix: Manually download the latest JAR from http://<master-host>:8080/jnlpJars/agent.jar and replace the existing file.

4. Inspect SSL and Handshake Logs

If you are using HTTPS/TLS for agent communication, a mismatch in certificates will cause the agent to disconnect immediately after the initial TCP handshake.

Check the jenkins-agent.log on the agent host for SSLHandshakeException. If found, ensure the agent's Java truststore contains the CA certificate used by the controller.

Verification and Result Check

To verify the fix, navigate to Manage Jenkins > Nodes. The agent should transition from a red "Offline" status to a green "In sync" or "Online" status. Check the agent's Log link in the UI to confirm the message: Agent successfully connected and registered.

Rollback Procedure

If you updated the Java version or the agent.jar and the connection failure worsened (e.g., the agent now crashes instantly), revert to the previous version:

1. Stop the agent process.
2. Restore the previous agent.jar from backup.
3. Revert the JAVA_HOME environment variable to the previous JDK path.
4. Restart the agent process.

Escalation Criteria

If the following conditions are met, elevate the issue to Network Engineering or Infrastructure:

• telnet fails, but the controller logs show no incoming connection attempts (indicates a network‑level drop).
• Intermittent disconnects occur every X minutes despite stable CPU/RAM (indicates a TCP timeout or load balancer idle‑timeout issue).
• SSL errors persist after importing the correct root CA into the Java truststore.