Diagnosing Jenkins Agent Offline Caused by JNLP Connection Failures

Recognizable condition

The Jenkins web UI shows an agent as offline. Hovering the agent icon often reveals a tooltip such as "Connection refused" or "Timeout while connecting to agent". In the master log ($JENKINS_HOME/logs/master.log) you see entries like:

ERROR: Failed to connect to agent
java.io.IOException: Connection reset by peer

On the agent host the agent log (agent.log or jenkins-agent.out) contains:

java.net.ConnectException: Connection refused
# or
javax.net.ssl.SSLHandshakeException (when TLS is enabled)

Cause / diagnostic quick‑reference table

Observed symptom	Most likely cause	Fast verification
Master logs "Connection reset by peer"	TCP packet dropped by firewall / security group	telnet <master-ip> 50000 from agent host
Agent logs "Connection refused"	JNLP port not listening on master or wrong port configured	ss -ltn | grep 50000 on master
Agent logs "SSLHandshakeException"	TLS certificate mismatch or missing truststore	Check -Djavax.net.ssl.trustStore on agent launch
Agent shows offline after a network change	NAT / routing rule no longer forwards JNLP traffic	Trace route traceroute <master-ip> from agent

Ordered diagnostic checks

1. Confirm master JNLP port – In Manage Jenkins → Configure Global Security → TCP port for JNLP agents note the port (default 50000). Run on master:

   ss -ltn | grep 50000
   # Expected: LISTEN 0 128 *:50000 *:*
   

   If the port is different, update the agent launch command accordingly.
2. Test TCP reachability from agent – On the agent host (requires outbound network access):

   telnet <master-ip> 50000
   # or
   nc -zv <master-ip> 50000
   

   A successful connection prints "Connected to …" or "succeeded!". Failure indicates a network block.
3. Inspect intermediate firewalls / security groups – Verify that rules allow traffic from master to agent on the JNLP port (or the reverse if using the "Connect to master" launch method). Cloud providers: check security group inbound rules for the agent instance; on‑prem: check iptables / firewalld.
4. Validate TLS configuration (if enabled) – When the master uses HTTPS for JNLP, the agent must trust the master’s certificate. Ensure the agent start command includes:

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

   Check the truststore contains the master’s CA (keytool -list -keystore …).
5. Review agent launch command version compatibility – Jenkins < 2.200 used the legacy JNLP3 protocol. If the master is newer but the agent was started with an old jnlp.jar, upgrade the agent jar (wget https://<master>/jnlpJars/agent.jar) and restart.

Fixes tied to findings

• Port mismatch – Update the master’s JNLP port and the agent’s -jnlpUrl or -url argument. Restart the agent process.
• Firewall block – Add an allow rule for TCP 50000 (or the configured port) between master and agent. Example for firewalld on the agent host:

  sudo firewall-cmd --permanent --add-port=50000/tcp
  sudo firewall-cmd --reload
  

  Risk: opening a port widens attack surface; restrict source IP to the master’s address where possible.
• TLS trust failure – Import the master’s CA into the agent truststore or disable TLS for JNLP (not recommended for production).
• Protocol version – Replace the old slave.jar with the current agent.jar from the master’s /jnlpJars/ endpoint.

Escalation criteria

Escalate to network or security teams when:

• TCP test succeeds but the agent still reports offline – indicates application‑level rejection (e.g., CSRF protection, reverse‑proxy mis‑configuration).
• Firewall rules appear correct but packets are dropped – may involve upstream network ACLs, VPC peering, or host‑based intrusion prevention.
• TLS errors persist after truststore update – could be certificate hostname mismatch or expired cert; requires PKI team involvement.

Verification of resolution

After applying a fix, confirm the agent returns to Online in the UI and the master log shows a successful handshake:

INFO: Agent connected: <agent-name>

Run a trivial job on the agent (e.g., echo hello) to prove the channel works end‑to‑end.

Limitations

• This guide covers the classic JNLP inbound connection (master → agent). The "Connect to master" (outbound) mode has a different port flow and is not addressed here.
• Older Jenkins releases (< 2.200) may require the legacy slave.jar and JNLP3 protocol; the steps above assume a modern LTS (≥ 2.300).
• Containerized agents (Docker, Kubernetes) often use the Kubernetes plugin’s WebSocket tunnel instead of raw JNLP; those scenarios need plugin‑specific troubleshooting.