{"record":{"id":"9ab14a3a73edee03","repo":"jenkinsci/jenkins","slug":"could-not-get-tcpslaveagentlistener-host-name","errorCode":null,"errorMessage":"Could not get TcpSlaveAgentListener host name","messagePattern":"Could not get TcpSlaveAgentListener host name","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"error","filePath":"core/src/main/java/hudson/TcpSlaveAgentListener.java","lineNumber":141,"sourceCode":"     * Gets the TCP port number in which we are advertising.\n     * @since 1.656\n     */\n    public int getAdvertisedPort() {\n        return CLI_PORT != null ? CLI_PORT : getPort();\n    }\n\n    /**\n     * Gets the host name that we advertise protocol clients to connect to.\n     * @since 2.198\n     */\n    public String getAdvertisedHost() {\n        if (CLI_HOST_NAME != null) {\n          return CLI_HOST_NAME;\n        }\n        try {\n            return new URL(Jenkins.get().getRootUrl()).getHost();\n        } catch (MalformedURLException e) {\n            throw new IllegalStateException(\"Could not get TcpSlaveAgentListener host name\", e);\n        }\n    }\n\n    /**\n     * Gets the Base64 encoded public key that forms part of this instance's identity keypair.\n     * @return the Base64 encoded public key\n     * @since 2.16\n     */\n    @Nullable\n    public String getIdentityPublicKey() {\n        RSAPublicKey key = InstanceIdentityProvider.RSA.getPublicKey();\n        return key == null ? null : Base64.getEncoder().encodeToString(key.getEncoded());\n    }\n\n    /**\n     * Returns a comma separated list of the enabled {@link AgentProtocol#getName()} implementations so that\n     * clients can avoid creating additional work for the server attempting to connect with unsupported protocols.\n     *","sourceCodeStart":123,"sourceCodeEnd":159,"githubUrl":"https://github.com/jenkinsci/jenkins/blob/2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc/core/src/main/java/hudson/TcpSlaveAgentListener.java#L123-L159","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"// Validate root URL before relying on getAdvertisedHost\nString rootUrl = Jenkins.get().getRootUrl();\nif (rootUrl == null || rootUrl.isEmpty()) {\n    throw new IllegalStateException(\"Jenkins Root URL is not configured. Set it in Manage Jenkins → System Configuration.\");\n}\ntry {\n    new URL(rootUrl); // validate parseability\n} catch (MalformedURLException e) {\n    throw new IllegalStateException(\"Jenkins Root URL is malformed: \" + rootUrl, e);\n}","typeGuard":null,"tryCatchPattern":"try {\n    String host = tcpSlaveAgentListener.getAdvertisedHost();\n} catch (IllegalStateException e) {\n    // Root URL is not set or malformed — fall back to system property or local hostname\n    String fallback = System.getProperty(\"hudson.TcpSlaveAgentListener.hostName\");\n    if (fallback != null) {\n        host = fallback;\n    } else {\n        throw e;\n    }\n}","preventionTips":["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."],"tags":["network","url","configuration","agent","cli"],"backgroundTag":null,"analyzedSha":"2e228ff40b14dbc8b14ffbc6edf0e4383cf744fc","analyzedAt":"2026-08-14T07:07:15.274Z","schemaVersion":2},"datasetVersion":"2026-08-14T10:17:34.591Z"}