apache/pulsar · critical · IllegalStateException

Failed to resolve localhost name.

Error message

Failed to resolve localhost name.

What it means

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.

Source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/ServiceConfigurationUtils.java:48

import org.apache.pulsar.policies.data.loadbalancer.AdvertisedListener;

@CustomLog
public class ServiceConfigurationUtils {

    public static String getDefaultOrConfiguredAddress(String configuredAddress) {
        if (isBlank(configuredAddress)) {
            return unsafeLocalhostResolve();
        }
        return configuredAddress;
    }

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

    /**
     * Get the address of Broker, first try to get it from AdvertisedAddress.
     * If it is not set, try to get the address set by advertisedListener.
     * If it is still not set, get it through InetAddress.getLocalHost().
     * @param configuration
     * @param ignoreAdvertisedListener Sometimes we can’t use the default key of AdvertisedListener,
     *                                 setting it to true can ignore AdvertisedListener.
     * @return
     */
    @Deprecated
    public static String getAppliedAdvertisedAddress(ServiceConfiguration configuration,
                                                     boolean ignoreAdvertisedListener) {
        Map<String, AdvertisedListener> result = MultipleListenerValidator
                .validateAndUpdateAdvertisedListeners(configuration);

View on GitHub (pinned to 820761864e)

Solutions

1. Fix host resolution: add the machine's hostname to /etc/hosts (e.g. 127.0.0.1 myhost) or fix DNS
2. Set advertisedAddress in broker.conf so unsafeLocalhostResolve() is never called
3. Verify with `hostname -f` that it resolves inside the container/host

Example fix

// before (broker.conf)
// advertisedAddress= (unset)
// after
advertisedAddress=broker1.example.com
// or /etc/hosts: 10.0.0.5 broker1

if (config.getAdvertisedAddress() == null || config.getAdvertisedAddress().isEmpty()) {
    // hostname must resolve; verify before broker start
    InetAddress.getByName(java.net.InetAddress.getLocalHost().getHostName());
}

try {
    String addr = ServiceConfigurationUtils.getDefaultOrConfiguredAddress(config);
} catch (IllegalStateException e) {
    log.fatal("hostname unresolvable: set advertisedAddress or fix /etc/hosts", e);
}

When it happens

Trigger: Broker startup calling getDefaultOrConfiguredAddress() (when advertisedAddress is not set) on a host whose hostname cannot be resolved back to an address.

Common situations: Containers/pods with hostname absent from /etc/hosts; DNS outages; misconfigured hostname in Kubernetes; minimal images lacking hosts entries.

Related errors

• Failed to resolve localhost name.
• Failed to bind Pulsar Proxy on port ${servicePort}
• Failed to start HTTP server on ports ${ports}
• No offloader found for driver '${driverName}'. Please make s
• Could not open configuration file

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