Agent using websocket fails to connect due to reverse proxy misconfiguration

Article ID:360053297331
1 minute readKnowledge base


When using WebSocket to connect agents to a Jenkins controller, if a reverse proxy is in use and is not configured correctly, the connection may fail with an error similar to this:

JNLP file https://my-jenkins-oc:8443/cjoc/jnlpSharedSlaves/my-controller/jenkins-agent.jnlp?encrypt=true has invalid arguments: [a12fec462afe7e70f2d92bd9ed51d9173509fe0eef9389da38e822310fa4cebd, my-controller, -webSocket, -url, https://my-jenkins-oc:8443/cjoc/, -url, https://my-jenkins-oc/cjoc/, -headless]
Most likely a configuration error in the master
-webSocket supports only a single -url


This error is ultimately caused by a misconfiguration of the reverse proxy in front of Jenkins, causing it to return multiple valid URLs for accessing the controller. The WebSocket agent connection can only accept a single URL argument. In versions of Jenkins (including CloudBees CI) newer than 2.246, this issue will no longer cause the agent connection to fail, but users will still want to address the underlying problem with their reverse proxy configuration as it may lead to other problems.


There are several possible workarounds:

  • Fix any reverse proxy configuration (such as nginx, Apache, etc.) issues.

  • Make sure that the "Jenkins URL" setting in Manage Jenkins -> Configure System is correct.

  • Upgrade to version 2.246 or newer.