{"record":{"id":"a63a42018a7d009a","repo":"apache/pulsar","slug":"failed-to-resolve-localhost-name","errorCode":null,"errorMessage":"Failed to resolve localhost name.","messagePattern":"Failed to resolve localhost name\\.","errorType":"validation","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"pulsar-broker-common/src/main/java/org/apache/pulsar/broker/ServiceConfigurationUtils.java","lineNumber":48,"sourceCode":"import org.apache.pulsar.policies.data.loadbalancer.AdvertisedListener;\n\n@CustomLog\npublic class ServiceConfigurationUtils {\n\n    public static String getDefaultOrConfiguredAddress(String configuredAddress) {\n        if (isBlank(configuredAddress)) {\n            return unsafeLocalhostResolve();\n        }\n        return configuredAddress;\n    }\n\n    public static String unsafeLocalhostResolve() {\n        try {\n            // Get the fully qualified hostname\n            return InetAddress.getLocalHost().getCanonicalHostName();\n        } catch (UnknownHostException ex) {\n            log.error().exception(ex).log(ex.getMessage());\n            throw new IllegalStateException(\"Failed to resolve localhost name.\", ex);\n        }\n    }\n\n    /**\n     * Get the address of Broker, first try to get it from AdvertisedAddress.\n     * If it is not set, try to get the address set by advertisedListener.\n     * If it is still not set, get it through InetAddress.getLocalHost().\n     * @param configuration\n     * @param ignoreAdvertisedListener Sometimes we can’t use the default key of AdvertisedListener,\n     *                                 setting it to true can ignore AdvertisedListener.\n     * @return\n     */\n    @Deprecated\n    public static String getAppliedAdvertisedAddress(ServiceConfiguration configuration,\n                                                     boolean ignoreAdvertisedListener) {\n        Map<String, AdvertisedListener> result = MultipleListenerValidator\n                .validateAndUpdateAdvertisedListeners(configuration);\n","sourceCodeStart":30,"sourceCodeEnd":66,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-broker-common/src/main/java/org/apache/pulsar/broker/ServiceConfigurationUtils.java#L30-L66","documentation":"ServiceConfigurationUtils.unsafeLocalhostResolve returns the machine's canonical hostname via InetAddress.getLocalHost(). If the JVM cannot resolve the local host (no mapping for the hostname in /etc/hosts, no reverse DNS), it throws UnknownHostException, which is wrapped in an IllegalStateException.","triggerScenarios":"Broker startup calling getDefaultOrConfiguredAddress() (when advertisedAddress is not set) on a host whose hostname cannot be resolved back to an address.","commonSituations":"Containers/pods with hostname absent from /etc/hosts; DNS outages; misconfigured hostname in Kubernetes; minimal images lacking hosts entries.","solutions":["Fix host resolution: add the machine's hostname to /etc/hosts (e.g. 127.0.0.1 myhost) or fix DNS","Set advertisedAddress in broker.conf so unsafeLocalhostResolve() is never called","Verify with `hostname -f` that it resolves inside the container/host"],"exampleFix":"// before (broker.conf)\n// advertisedAddress= (unset)\n// after\nadvertisedAddress=broker1.example.com\n// or /etc/hosts: 10.0.0.5 broker1","handlingStrategy":"validation","validationCode":"if (config.getAdvertisedAddress() == null || config.getAdvertisedAddress().isEmpty()) {\n    // hostname must resolve; verify before broker start\n    InetAddress.getByName(java.net.InetAddress.getLocalHost().getHostName());\n}","typeGuard":null,"tryCatchPattern":"try {\n    String addr = ServiceConfigurationUtils.getDefaultOrConfiguredAddress(config);\n} catch (IllegalStateException e) {\n    log.fatal(\"hostname unresolvable: set advertisedAddress or fix /etc/hosts\", e);\n}","preventionTips":["Always set advertisedAddress in containerized/K8s deployments","Ensure hostname has an /etc/hosts entry","Test `hostname -f` in the deployment image"],"tags":["network","dns","hostname","startup"],"backgroundTag":"unknown-host","analyzedSha":"820761864ed8e2a7d2e52dd9763ad2ae117c1395","analyzedAt":"2026-09-06T00:14:20.138Z","contentChangedAt":"2026-09-06T00:14:20.138Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}