How to troubleshoot JNLP slaves connection issues with Jenkins?


Your JNLP slave cannot be connected with your Jenkins master.


  • CloudBees Jenkins Enterprise
  • CloudBees Jenkins Operations Center


Ensure that the Java version is at least on the same line on both master and slave

A good practice is to run the exactly same Java version in both Jenkins and slave, but when this is not possible it is recommendable to be running at least the same base line.

Run java -version in both Jenkins master box and slave to check the java version you are running in both.

Ensure that the version of slave.jar matches with the one

The main problem of running JNLP as a slave Launcher is that when you upgrade Jenkins slave.jar is not automatically upgraded on the slave - which by the way happens in SSH Launcher out of the box.

Check that slave.jar is the same using for example md5sum slave.jar. slave.jar can be downloaded from Jenkins master from the URL below:


Use jenkins-cli to check the connection

In the slave box download http:///jnlpJars/jenkins-cli.jar from Jenkins master and execute the command below:

java -jar jenkins-cli.jar -s http://<CJOC_URL>/ --username=<USERNAME> --password=<PASSWORD> help

Check that the JNLP port and hostname are right

Launch the commands below and check that the port and hostname are the right ones:

curl -I http://<JENKINS_URL>/computer/<SLAVE>/slave-agent.jnlp
curl -I  http://<JENKINS_URL>/tcpSlaveAgentListener/

Curl command can be available on a Windows box using for example curl Download Wizard

Load balancer or ha-proxy

If you are using a load balancer or a ha-proxy and you are not running Jenkins on ha mode, you might want to bypass any of them through the Slave advance option of Tunnel connection through.

Information to be attached in case you need to open a Support ticket at CloudBees Support

  • Architecture diagram so we can understand how it looks like your environment
  • md5sum of slave.jar in both boxes
  • Content of http:///computer//slave-agent.jnlp
  • Content of http:///computer//config.xml
  • Output of commands below launched from slave box
curl -I http://<JENKINS_URL>/computer/<SLAVE>/slave-agent.jnlp
curl -I  http://<JENKINS_URL>/tcpSlaveAgentListener/
  • Output from jenkins-cli launched from slave box
Have more questions? Submit a request


  • -1
    John Mellor

    Ok, what is a "CJOC_URL"?  Gobbledegook phrase meaning "Canadian Joint Operations Command"?

    If the slave.jar has a different md5, how do I interpret that?  What API versions are compatible, and how do I determine that compatibility?

    I have a JNLP connection issue in K8S, and this document falls far short of what is required to debug this.

  • 0
    Denys Digtiar

    CJOC stands for CloudBees Jenkins Enterprise. For the purposes of this article, it should have just been JENKINS_URL.

    If the hash sum is different it means the versions are different between master and agent. The backward compatibility is maintained but the recommendation is to keep the slave.jar at the same version on both sides. Therefore if md5 is different, replace agent's slave.jar with the one downloaded from the master.

  • 0
    Byron Kim

    In the Load balancer or ha-proxy section, there should be a comment about Idle Timeouts if you're Jenkins node is running through a LB/proxy.  This can cause JNLP connection timeout errors

    The default for ELB for instance is 60s and was causing some builds on slave nodes to fail on certain steps that took a long time to respond.

Please sign in to leave a comment.