apache/pulsar · critical · IllegalStateException

Failed to resolve localhost name.

Error message

Failed to resolve localhost name.

What it means

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.

Source

Thrown at pulsar-functions/runtime/src/main/java/org/apache/pulsar/functions/worker/WorkerConfig.java:979

        } else {
            return null;
        }
    }

    public String getWorkerWebAddress() {
        return String.format("http://%s:%d", this.getWorkerHostname(), this.getWorkerPort());
    }

    public String getWorkerWebAddressTls() {
        return String.format("https://%s:%d", this.getWorkerHostname(), this.getWorkerPortTls());
    }

    public static String unsafeLocalhostResolve() {
        try {
            // Get the fully qualified hostname
            return InetAddress.getLocalHost().getCanonicalHostName();
        } catch (UnknownHostException ex) {
            throw new IllegalStateException("Failed to resolve localhost name.", ex);
        }
    }

    public String getConfigurationMetadataStoreUrl() {
        if (StringUtils.isNotBlank(configurationMetadataStoreUrl)) {
            return configurationMetadataStoreUrl;
        } else {
            return configurationStoreServers;
        }
    }

    @Override
    public void setProperties(Properties properties) {
        this.properties = properties;
    }

    // --------- DEPRECATED CONFIGS ---------

View on GitHub (pinned to 820761864e)

Solutions

1. Add the machine's hostname to /etc/hosts (e.g. '127.0.0.1 myhost myhost.local' or the host's real IP).
2. Verify with `hostname` and `hostname -f` (or `ping $(hostname)`) that the name resolves; fix DNS if not.
3. In containers, ensure the entrypoint/container runtime passes --hostname with a resolvable name or that the hostname maps to 127.0.0.1.
4. Check /etc/nsswitch.conf ordering so 'hosts' includes 'files' before 'dns'.

Example fix

// before (broken /etc/hosts)
127.0.0.1   localhost
// after
127.0.0.1   localhost
192.168.1.10 pulsar-worker pulsar-worker.cluster.local

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() + "'"); }

boolean localhostResolvable() { try { java.net.InetAddress.getLocalHost(); return true; } catch (java.net.UnknownHostException e) { return false; } }

try { String host = WorkerConfig.unsafeLocalhostResolve(); } catch (IllegalStateException e) { log.error("Hostname not resolvable: {}", e.getCause()); throw e; // fail fast at startup }

When it happens

Trigger: 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).

Common situations: 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.

Related errors

• Failed to resolve localhost name.
• Timeout during mark-delete operation
• Timeout during clear backlog operation
• Timeout during skip messages operation
• Timeout during delete operation

AI-assisted analysis of apache/pulsar@820761864e (2026-09-06). Data as JSON: /api/errors/fb613e60011ac9d3. Report an issue: GitHub.