Introduction

Jenkins agents connect to the controller using the JNLP (Java Network Launch Protocol) protocol. During the handshake, the agent authenticates with the controller and establishes a communication channel. If the handshake times out -- due to network issues, firewall rules, or controller overload -- the agent cannot connect and any running builds on that agent fail immediately.

Symptoms

  • Agent shows Offline in Jenkins UI with JNLP connection lost
  • Running builds fail with channel is already closed or connection was aborted
  • Agent logs show JNLP handshake timed out or connection refused
  • Agent reconnect attempts fail repeatedly
  • Error message: java.io.IOException: JNLP agent connection timeout after 30000ms

Common Causes

  • Network firewall blocking JNLP port (default 50000) between agent and controller
  • Jenkins controller overloaded, not responding to JNLP connection requests in time
  • Agent running on a different network with high latency to the controller
  • TLS/SSL configuration mismatch between agent and controller
  • Jenkins controller restarted while agents were connected

Step-by-Step Fix

  1. 1.Check JNLP port connectivity from the agent: Verify network reachability.
  2. 2.```bash
  3. 3.nc -zv jenkins-controller.example.com 50000
  4. 4.# Should show: Connection succeeded
  5. 5.`
  6. 6.Verify the JNLP port is configured correctly on the controller: Check the port setting.
  7. 7.`
  8. 8.# Jenkins UI: Manage Jenkins > Security > Agents
  9. 9.# Verify TCP port for JNLP agents is set (e.g., 50000)
  10. 10.# Or set to Random to avoid conflicts
  11. 11.`
  12. 12.Restart the agent connection with increased timeout: Give the handshake more time.
  13. 13.```bash
  14. 14.java -jar agent.jar \
  15. 15.-jnlpUrl https://jenkins.example.com/computer/my-agent/slave-agent.jnlp \
  16. 16.-secret <secret> \
  17. 17.-workDir "/home/jenkins" \
  18. 18.-jar-cache /home/jenkins/jar-cache \
  19. 19.-connectTimeout 60000 \
  20. 20.-retry 10
  21. 21.`
  22. 22.Check controller resource utilization: Ensure the controller can handle connections.
  23. 23.```bash
  24. 24.# Check Jenkins controller memory and CPU
  25. 25.top -p $(pidof java)
  26. 26.# Check Jenkins logs for OOM or GC issues
  27. 27.tail -100 /var/log/jenkins/jenkins.log
  28. 28.`
  29. 29.Configure agent reconnection with exponential backoff: Improve connection resilience.
  30. 30.```bash
  31. 31.# Create a systemd service for the agent
  32. 32.cat > /etc/systemd/system/jenkins-agent.service <<EOF
  33. 33.[Unit]
  34. 34.Description=Jenkins Agent
  35. 35.After=network.target

[Service] ExecStart=/usr/bin/java -jar /opt/jenkins/agent.jar \ -jnlpUrl https://jenkins.example.com/computer/my-agent/slave-agent.jnlp \ -secret <secret> -workDir "/home/jenkins" -retry 10 Restart=always RestartSec=30

[Install] WantedBy=multi-user.target EOF systemctl enable jenkins-agent systemctl start jenkins-agent ```

Prevention

  • Configure firewall rules to allow JNLP port traffic between all agents and the controller
  • Use WebSocket mode (-webSocket) for agent connections to traverse firewalls more easily
  • Set up health monitoring for agent connections and alert on disconnections
  • Use cloud-based agents that automatically reconnect after controller restarts
  • Configure Jenkins controller with adequate memory to handle all agent connections
  • Implement agent connection retry logic with exponential backoff in deployment scripts