apache/pulsar · error · IllegalStateException

Failed to update url

Error message

Failed to update url 

What it means

When getLookup(serviceUrl) cannot create a LookupService for the given URL (createLookup throws PulsarClientException), the client logs a warning ('Failed to update url to lookup service') and rethrows as IllegalStateException('Failed to update url ' + url). It means the URL could not be mapped to any usable lookup service. The message is truncated by exception formatting; the URL identifies the failing endpoint.

Source

Thrown at pulsar-client/src/main/java/org/apache/pulsar/client/impl/PulsarClientImpl.java:1790

    public CompletableFuture<ClientCnx> getConnection(final String topic, final String url) {
        TopicName topicName = TopicName.get(topic);
        return getLookup(url).getBroker(topicName)
                .thenCompose(lookupResult -> getConnection(lookupResult.getLogicalAddress(),
                        lookupResult.getPhysicalAddress(), cnxPool.genRandomKeyToSelectCon()));
    }

    public LookupService getLookup(String serviceUrl) {
        return urlLookupMap.computeIfAbsent(serviceUrl, url -> {
            if (isClosed()) {
                throw new IllegalStateException("Pulsar client has been closed, can not build LookupService when"
                        + " calling get lookup with an url");
            }
            try {
                return createLookup(serviceUrl);
            } catch (PulsarClientException e) {
                log.warn().attr("service", url).exceptionMessage(e).log("Failed to update url to lookup service");
                throw new IllegalStateException("Failed to update url " + url);
            }
        });
    }

    public CompletableFuture<ClientCnx> getConnectionToServiceUrl() {
        if (!lookup.isBinaryProtoLookupService()) {
            return FutureUtil.failedFuture(new PulsarClientException.InvalidServiceURL(
                    "Can't get client connection to HTTP service URL", null));
        }
        InetSocketAddress address = lookup.resolveHost();
        return getConnection(address, address, cnxPool.genRandomKeyToSelectCon());
    }

    /**
     * Open a connection to the proxy and ask it to pair the connection to any broker it selects
     * (an empty proxyToBrokerUrl). Used for control-plane operations that aren't tied to a specific
     * broker (e.g. scalable-topic subscribe/namespace-watch) when connecting through a proxy.
     */

View on GitHub (pinned to 820761864e)

Solutions

1. Fix the service URL scheme/shape to one the client supports (pulsar://, pulsar+ssl://, or http/https when HTTP lookup is available).
2. Check the preceding WARN log 'Failed to update url to lookup service' for the underlying PulsarClientException cause.
3. Validate URLs from external/discovery configuration before passing them to getLookup.

Example fix

// before
client.getLookup("htt://broker:8080"); // bad scheme
// after
client.getLookup("pulsar://broker:6650");

if (!url.startsWith("pulsar://") && !url.startsWith("pulsar+ssl://")
        && !url.startsWith("http://") && !url.startsWith("https://")) {
    throw new IllegalArgumentException("Unsupported lookup service URL scheme: " + url);
}

try {
    LookupService ls = client.getLookup(url);
} catch (IllegalStateException e) {
    if (e.getMessage().startsWith("Failed to update url")) {
        log.warn("Cannot map {} to a lookup service", url, e);
    } else throw e;
}

When it happens

Trigger: Calling getLookup(url) with a malformed or unsupported service URL scheme, or with a URL for which createLookup cannot construct a binary/HTTP lookup service (bad scheme, missing http client, invalid host).

Common situations: Passing an http:// URL to a client built for the binary protocol (or vice versa); typos in the scheme (pulsar:// vs pulsar+ssl:// vs http://); URLs loaded from a broker discovery list containing unsupported schemes.

Related errors

• The schema is not a KeyValueSchema
• Pulsar client has been closed, can not build LookupService w
• Cannot set resourceTypes when shareConfigured() has already
• Cannot use shareConfigured() when resourceTypes has already
• Cannot decode a message without schema

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