apache/pulsar · error · IllegalArgumentException

Invalid hostname : ${hostname}

Error message

Invalid hostname : ${hostname}

What it means

ServiceURI.create validates each host part by parsing 'dummyscheme://<hostname>' with java.net.URI. If URI.create itself throws IllegalArgumentException (malformed URI syntax) the hostname is rejected with 'Invalid hostname : <hostname>'. This means the string between ':' separators is not a syntactically valid host.

Source

Thrown at pulsar-common/src/main/java/org/apache/pulsar/common/net/ServiceURI.java:176

            "service path component is missing in service uri : " + uri);

        return new ServiceURI(
            serviceName,
            serviceInfos,
            serviceUser,
            serviceHosts.toArray(new String[serviceHosts.size()]),
            servicePath,
            uri);
    }

    private static String validateHostName(String serviceName,
                                           String[] serviceInfos,
                                           String hostname) {
        URI uri = null;
        try {
            uri = URI.create("dummyscheme://" + hostname);
        } catch (IllegalArgumentException e) {
            throw new IllegalArgumentException("Invalid hostname : " + hostname);
        }
        String host = uri.getHost();
        if (host == null) {
            throw new IllegalArgumentException("Invalid hostname : " + hostname);
        }
        int port = uri.getPort();
        if (port == -1) {
            port = getServicePort(serviceName, serviceInfos);
        }
        return host + ":" + port;
    }

    private final String serviceName;
    private final String[] serviceInfos;
    private final String serviceUser;
    private final String[] serviceHosts;
    private final String servicePath;
    private final URI uri;

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the hostname in the serviceUrl: remove illegal characters (spaces, underscores) and percent-encode if needed.
2. Bracket IPv6 addresses: pulsar://[fe80::1]:6650 instead of pulsar://fe80::1:6650.
3. Ensure the host segment is non-empty between scheme:// and :port.
4. Validate the host before calling ServiceURI.create (see validationCode).

Example fix

// before
ServiceURI u = ServiceURI.create("pulsar://my_broker:6650");
// after
ServiceURI u = ServiceURI.create("pulsar://my-broker.example.com:6650");
// or for IPv6
ServiceURI u = ServiceURI.create("pulsar://[2001:db8::1]:6650");

static void assertValidHost(String host) {
    URI u = URI.create("dummyscheme://" + host); // throws IllegalArgumentException
    if (u.getHost() == null) {
        throw new IllegalArgumentException("Invalid hostname : " + host);
    }
}
// call assertValidHost(host) before ServiceURI.create(...)

static boolean isParsableHost(String host) {
    try {
        return URI.create("dummyscheme://" + host).getHost() != null;
    } catch (IllegalArgumentException e) {
        return false;
    }
}

try {
    ServiceURI uri = ServiceURI.create(serviceUrl);
} catch (IllegalArgumentException e) {
    if (e.getMessage().startsWith("Invalid hostname")) {
        // fix hostname: no spaces/underscores; bracket IPv6 like [fe80::1]
    }
    throw e;
}

When it happens

Trigger: Calling ServiceURI.create('pulsar://<bad-host>:6650') where the host part contains characters illegal in a URI authority — spaces, underscores, unbracketed IPv6 like '::1', multiple colons, empty host segments like 'pulsar://:6650'.

Common situations: Pasting a serviceUrl with a typo (space or underscore in hostname); using an unbracketed IPv6 address; building the URI by string concatenation with an unresolved/empty host variable.

Related errors

• Invalid pulsar service : ${serviceName}+${serviceInfos}
• Invalid pulsar service : ${serviceName}
• Failed to resolve localhost name.
• host must not be null
• the value ${strUri} in the `advertisedListeners` configure i

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