What causes "Could not get TcpSlaveAgentListener host name" in jenkinsci/jenkins?

Set a valid Jenkins Root URL in Manage Jenkins → System Configuration (must include http:// or https:// scheme and a hostname, e.g., 'https://jenkins.example.com').

jenkinsci/jenkins · error · IllegalStateException

Could not get TcpSlaveAgentListener host name

Error message

Could not get TcpSlaveAgentListener host name

What it means

Thrown by TcpSlaveAgentListener.getAdvertisedHost() when CLI_HOST_NAME system property is null and Jenkins.get().getRootUrl() cannot be parsed as a valid URL (MalformedURLException). getAdvertisedHost returns the hostname that CLI clients and agent protocols use to connect, derived from the configured Jenkins Root URL.

Source

Thrown at core/src/main/java/hudson/TcpSlaveAgentListener.java:141

     * Gets the TCP port number in which we are advertising.
     * @since 1.656
     */
    public int getAdvertisedPort() {
        return CLI_PORT != null ? CLI_PORT : getPort();
    }

    /**
     * Gets the host name that we advertise protocol clients to connect to.
     * @since 2.198
     */
    public String getAdvertisedHost() {
        if (CLI_HOST_NAME != null) {
          return CLI_HOST_NAME;
        }
        try {
            return new URL(Jenkins.get().getRootUrl()).getHost();
        } catch (MalformedURLException e) {
            throw new IllegalStateException("Could not get TcpSlaveAgentListener host name", e);
        }
    }

    /**
     * Gets the Base64 encoded public key that forms part of this instance's identity keypair.
     * @return the Base64 encoded public key
     * @since 2.16
     */
    @Nullable
    public String getIdentityPublicKey() {
        RSAPublicKey key = InstanceIdentityProvider.RSA.getPublicKey();
        return key == null ? null : Base64.getEncoder().encodeToString(key.getEncoded());
    }

    /**
     * Returns a comma separated list of the enabled {@link AgentProtocol#getName()} implementations so that
     * clients can avoid creating additional work for the server attempting to connect with unsupported protocols.
     *

View on GitHub (pinned to 2e228ff40b)

Solutions

Set a valid Jenkins Root URL in Manage Jenkins → System Configuration (must include http:// or https:// scheme and a hostname, e.g., 'https://jenkins.example.com').
As a fallback or override, set the system property -Dhudson.TcpSlaveAgentListener.hostName=<hostname> (maps to CLI_HOST_NAME) to bypass Root URL parsing entirely.
If this occurs during startup before configuration is loaded, ensure JENKINS_HOME/config.xml has a valid <jenkinsUrl> or <rootUrl> entry.
Verify the URL does not contain trailing paths that confuse URL.getHost() — the host extraction relies on a well-formed URL.

Defensive patterns

Strategy: validation

Validate before calling

// Validate root URL before relying on getAdvertisedHost
String rootUrl = Jenkins.get().getRootUrl();
if (rootUrl == null || rootUrl.isEmpty()) {
    throw new IllegalStateException("Jenkins Root URL is not configured. Set it in Manage Jenkins → System Configuration.");
}
try {
    new URL(rootUrl); // validate parseability
} catch (MalformedURLException e) {
    throw new IllegalStateException("Jenkins Root URL is malformed: " + rootUrl, e);
}

Try / catch

try {
    String host = tcpSlaveAgentListener.getAdvertisedHost();
} catch (IllegalStateException e) {
    // Root URL is not set or malformed — fall back to system property or local hostname
    String fallback = System.getProperty("hudson.TcpSlaveAgentListener.hostName");
    if (fallback != null) {
        host = fallback;
    } else {
        throw e;
    }
}

Prevention

Always configure a valid Jenkins Root URL during initial setup.
Set -Dhudson.TcpSlaveAgentListener.hostName as a safety net in environments where Root URL may be unset.
Include Root URL validation in Jenkins health checks.

When it happens

Trigger: getAdvertisedHost() is called when CLI_HOST_NAME is unset; Jenkins.get().getRootUrl() returns null or a malformed string; new URL(rootUrl) throws MalformedURLException; the IllegalStateException wraps it.

Common situations: Jenkins Root URL is not configured (left empty in Setup Wizard or Global Security); Root URL is set to a relative path like '/jenkins' without scheme/host; Root URL contains invalid characters; a plugin or CLI command calls getAdvertisedHost() before initial setup is complete.

Related errors

AI-assisted analysis of jenkinsci/jenkins@2e228ff40b (2026-08-14). Data as JSON: /api/errors/9ab14a3a73edee03. Report an issue: GitHub.