{"record":{"id":"fb613e60011ac9d3","repo":"apache/pulsar","slug":"failed-to-resolve-localhost-name-fb613e","errorCode":null,"errorMessage":"Failed to resolve localhost name.","messagePattern":"Failed to resolve localhost name\\.","errorType":"exception","errorClass":"IllegalStateException","httpStatus":null,"severity":"critical","filePath":"pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/worker/WorkerConfig.java","lineNumber":979,"sourceCode":"        } else {\n            return null;\n        }\n    }\n\n    public String getWorkerWebAddress() {\n        return String.format(\"http://%s:%d\", this.getWorkerHostname(), this.getWorkerPort());\n    }\n\n    public String getWorkerWebAddressTls() {\n        return String.format(\"https://%s:%d\", this.getWorkerHostname(), this.getWorkerPortTls());\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            throw new IllegalStateException(\"Failed to resolve localhost name.\", ex);\n        }\n    }\n\n    public String getConfigurationMetadataStoreUrl() {\n        if (StringUtils.isNotBlank(configurationMetadataStoreUrl)) {\n            return configurationMetadataStoreUrl;\n        } else {\n            return configurationStoreServers;\n        }\n    }\n\n    @Override\n    public void setProperties(Properties properties) {\n        this.properties = properties;\n    }\n\n    // --------- DEPRECATED CONFIGS ---------\n","sourceCodeStart":961,"sourceCodeEnd":997,"githubUrl":"https://github.com/apache/pulsar/blob/820761864ed8e2a7d2e52dd9763ad2ae117c1395/pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/worker/WorkerConfig.java#L961-L997","documentation":"WorkerConfig.unsafeLocalhostResolve() resolves the local machine's canonical hostname via InetAddress.getLocalHost(). If the JVM cannot map the local host name to an address (or vice versa) it throws UnknownHostException, which is rethrown as an IllegalStateException wrapping the original cause. Pulsar relies on this at worker startup to determine its advertised address, so an unresolvable hostname is fatal.","triggerScenarios":"Calling WorkerConfig.unsafeLocalhostResolve() (directly or indirectly during function worker startup) on a host where /etc/hosts lacks an entry for the machine's hostname, DNS is misconfigured, or the hostname is set but not resolvable (e.g. container with hostname not registered).","commonSituations":"Docker/Kubernetes pods whose hostname isn't in /etc/hosts; freshly provisioned VMs with hostname set but no resolver entry; DNS outages; Alpine-based images missing nsswitch configuration; laptops after network changes.","solutions":["Add the machine's hostname to /etc/hosts (e.g. '127.0.0.1 myhost myhost.local' or the host's real IP).","Verify with `hostname` and `hostname -f` (or `ping $(hostname)`) that the name resolves; fix DNS if not.","In containers, ensure the entrypoint/container runtime passes --hostname with a resolvable name or that the hostname maps to 127.0.0.1.","Check /etc/nsswitch.conf ordering so 'hosts' includes 'files' before 'dns'."],"exampleFix":"// before (broken /etc/hosts)\n127.0.0.1   localhost\n// after\n127.0.0.1   localhost\n192.168.1.10 pulsar-worker pulsar-worker.cluster.local","handlingStrategy":"try-catch","validationCode":"try { java.net.InetAddress.getLocalHost().getCanonicalHostName(); } catch (java.net.UnknownHostException e) { throw new IllegalStateException(\"Fix /etc/hosts: add an entry for '\" + java.net.InetAddress.getLocalHost() + \"'\"); }","typeGuard":"boolean localhostResolvable() { try { java.net.InetAddress.getLocalHost(); return true; } catch (java.net.UnknownHostException e) { return false; } }","tryCatchPattern":"try { String host = WorkerConfig.unsafeLocalhostResolve(); } catch (IllegalStateException e) { log.error(\"Hostname not resolvable: {}\", e.getCause()); throw e; // fail fast at startup }","preventionTips":["Always include the machine hostname in /etc/hosts pointing at 127.0.0.1 or the host IP.","Smoke-test `hostname -f` in container/VM image build pipelines.","Set explicit hostname in container runtime args and map it in hosts entries.","Keep 'files' before 'dns' in /etc/nsswitch.conf hosts line."],"tags":["network","dns","hostname-resolution","configuration"],"backgroundTag":"localhost-unresolved","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"}