Fix Jenkins JNLP Agent Connection Failed Errors (2026)

The Jenkins JNLP agent failed to connect because the Jenkins controller, acting as the server, could not establish a persistent WebSocket or TCP connection with the agent process, which was trying to register itself.

Common Causes and Fixes:

Network Firewall Blocking Ports: The most frequent culprit is a firewall, either on the Jenkins controller, the agent host, or an intermediate network device, blocking the necessary ports. JNLP agents typically connect on port 50000 (for outbound connections from agent to controller) or the controller’s port (usually 8080 or 8443) if the agent is initiating a connection that is then redirected.
- Diagnosis: On the agent machine, try to telnet to the Jenkins controller’s IP/hostname and port. From the controller machine, try to telnet to the agent’s IP/hostname and port 50000.
```
# On agent machine, to controller's web port (e.g., 8080)
telnet <jenkins_controller_hostname_or_ip> 8080

# On controller machine, to agent's JNLP port (e.g., 50000)
telnet <jenkins_agent_hostname_or_ip> 50000
```
  If telnet hangs or immediately disconnects, the port is likely blocked.
- Fix: Open the relevant ports in your firewalls. For example, on firewalld on the controller:
```
sudo firewall-cmd --zone=public --add-port=8080/tcp --permanent
sudo firewall-cmd --reload
```
  And on the agent (if it’s listening on 50000):
```
sudo firewall-cmd --zone=public --add-port=50000/tcp --permanent
sudo firewall-cmd --reload
```
  Alternatively, if using ufw:
```
sudo ufw allow 8080/tcp
sudo ufw allow 50000/tcp
sudo ufw reload
```
- Why it works: This explicitly permits network traffic on the ports Jenkins uses for JNLP communication, allowing the handshake and data exchange to occur.
Incorrect JNLP Agent URL in jenkins-agent.jnlp: The jenkins-agent.jnlp file downloaded from Jenkins contains the URL the agent should use to connect. If this URL is mistyped, points to the wrong controller, or uses an incorrect protocol (HTTP vs. HTTPS), the connection will fail.
- Diagnosis: Download the jenkins-agent.jnlp file from the agent configuration page in Jenkins. Open it with a text editor and examine the <jnlp> tag, specifically the codebase attribute, and the <application-content> tag.
```
<jnlp spec="1.0+" codebase="http://your-jenkins-controller:8080/">
  <information>
    <title>Agent for Jenkins</title>
    <vendor>Jenkins Project</vendor>
  </information>
  <resources>
    <j2se version="1.8+" href="http://java.sun.com/products/autodl/j2se"/>
    <jar href="agent.jar" main="true"/>
  </resources>
  <application-desc main-class="hudson.remoting.jnlp.Main">
    <argument>your-jenkins-controller:50000</argument>
  </application-desc>
</jnlp>
```
  The codebase should match your Jenkins controller’s URL, and the argument after <argument> is the host and port the agent attempts to connect to.
- Fix: Ensure the codebase URL and the argument in the jenkins-agent.jnlp file are correct. If they are wrong, go to "Manage Jenkins" -> "Nodes" -> click on the agent -> "Configure" -> "Agent launch method" and correct the "Jenkins URL" or the agent configuration itself. Then re-download the jenkins-agent.jnlp file.
- Why it works: Providing the correct target URL ensures the agent process knows where to initiate its connection attempt.
Agent Process Not Running or Crashed: The agent process might not have started, or it might have crashed shortly after starting due to an unhandled exception or resource issue.
- Diagnosis: Check the process list on the agent machine for java processes that look like the Jenkins agent. Look for agent.jar in their command line. Also, check the agent’s log file for any errors.
```
# On agent machine
ps aux | grep java
# Look for a java process running agent.jar
```
  If no such process is found, or if it’s short-lived, investigate why it’s not starting or crashing. Check the output of the command used to launch the agent.
- Fix: Ensure the command to launch the agent is correct and that the necessary Java runtime environment (JRE) is installed and accessible. For example, if launching manually:
```
java -jar /path/to/agent.jar -jnlpUrl http://your-jenkins-controller:8080/computer/your-agent-name/jenkins-agent.jnlp -secret <your-secret-key>
```
  If it’s running as a service, check the service status and logs.
- Why it works: This ensures the agent process is actively running and listening for connections from the controller.
JNLP Secret Mismatch or Expired: The secret key used to authenticate the agent with the controller might be incorrect, or if it was generated a long time ago and the agent configuration was re-saved without updating the secret, it could be stale.
- Diagnosis: Compare the secret key shown in the Jenkins agent configuration page ("Manage Jenkins" -> "Nodes" -> agent -> "Configure") with the secret key being used by the agent process (often passed as a command-line argument or in an agent configuration file).
- Fix: Copy the current secret key from the Jenkins UI and update the agent’s startup command or configuration file with the correct, current secret. If you don’t see a secret, click "Show".
```
# Example using command-line secret
java -jar agent.jar -jnlpUrl http://your-jenkins-controller:8080/computer/your-agent-name/jenkins-agent.jnlp -secret abcdef1234567890abcdef1234567890
```
- Why it works: The secret key is a one-time password or shared secret used for initial authentication. A correct, current secret allows the agent to prove its identity to the controller.
Jenkins Controller Overloaded or Unresponsive: If the Jenkins controller itself is under heavy load, experiencing high CPU, memory, or disk I/O, it might be too slow to accept new JNLP connections or keep existing ones alive.
- Diagnosis: Monitor the Jenkins controller’s system resources (CPU, memory, disk I/O). Check Jenkins system logs for any signs of slowness, OutOfMemoryError, or long garbage collection pauses. Also, check the Jenkins controller’s own network connectivity and responsiveness.
- Fix: Address the root cause of the controller’s load. This might involve adding more resources (CPU, RAM), optimizing Jenkins jobs, increasing heap size for the Jenkins JVM, or moving Jenkins to more powerful hardware. For example, increasing heap size by adding -Xmx4g to the Jenkins startup script (e.g., jenkins.sh or jenkins.xml).
- Why it works: A healthy and responsive Jenkins controller can dedicate resources to managing agent connections, ensuring reliable communication.
Java Version Incompatibility (Agent vs. Controller): While less common for JNLP, significant differences in Java versions between the controller and the agent, or issues with the Java runtime on the agent, can sometimes cause connection problems.
- Diagnosis: Check the Java version on the Jenkins controller and the agent machine.
```
# On controller and agent
java -version
```
  Ensure both are running a supported and compatible Java version (e.g., Java 8 or 11 are common).
- Fix: Install or configure the agent to use a compatible Java version. Jenkins typically requires Java 8 or higher for the controller and recommends a compatible version for agents. Ensure JAVA_HOME is set correctly on the agent if launching manually or via a service.
- Why it works: Consistent and compatible Java runtimes reduce the chances of low-level communication or serialization issues between the controller and agent.
Proxy Configuration Issues: If the Jenkins controller or agent is behind a proxy server, incorrect proxy settings can prevent the JNLP connection from being established.
- Diagnosis: Examine the Jenkins controller’s JVM proxy settings (e.g., http.proxyHost, https.proxyHost, noProxy) and the agent’s environment variables or JVM arguments for proxy settings.
- Fix: Ensure the proxy settings are correctly configured for both the controller and the agent. For the agent, you might need to set JVM system properties when launching it:
```
java -Dhttp.proxyHost=your.proxy.com -Dhttp.proxyPort=8080 -jar agent.jar ...
```
  For the controller, these are usually set in jenkins.xml or jenkins.sh.
- Why it works: Correct proxy configuration allows the JNLP connection to traverse the network infrastructure as intended.

After fixing these issues, the next error you’ll likely encounter is a "JNLP agent disconnected" error if the agent was previously connected but the underlying issue caused it to drop.