apache/pulsar · error · PulsarClientException.InvalidConfigurationException

Invalid client configuration

Error message

Invalid client configuration

What it means

Thrown from the PulsarClientImpl constructor when the ClientConfigurationData is null or its serviceUrl is blank. A client cannot resolve brokers without a service URL, so construction fails immediately with InvalidConfigurationException instead of deferring the failure to the first operation.

Source

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

                            ScheduledExecutorProvider scheduledExecutorProvider)
            throws PulsarClientException {
        this(conf, eventLoopGroup, connectionPool, timer, externalExecutorProvider, internalExecutorProvider,
                scheduledExecutorProvider, null, null, null);
    }

    @Builder(builderClassName = "PulsarClientImplBuilder")
    PulsarClientImpl(ClientConfigurationData conf, EventLoopGroup eventLoopGroup, ConnectionPool connectionPool,
                     Timer timer, ExecutorProvider externalExecutorProvider,
                     ExecutorProvider internalExecutorProvider,
                     ScheduledExecutorProvider scheduledExecutorProvider,
                     ExecutorProvider lookupExecutorProvider,
                     DnsResolverGroupImpl dnsResolverGroup,
                     MemoryLimitController memoryLimitController) throws PulsarClientException {
        EventLoopGroup eventLoopGroupReference = null;
        ConnectionPool connectionPoolReference = null;
        try {
            if (conf == null || isBlank(conf.getServiceUrl())) {
                throw new PulsarClientException.InvalidConfigurationException("Invalid client configuration");
            }
            this.conf = conf;
            this.createdEventLoopGroup = eventLoopGroup == null;
            this.createdCnxPool = connectionPool == null;
            if ((externalExecutorProvider == null) != (internalExecutorProvider == null)) {
                throw new IllegalArgumentException(
                        "Both externalExecutorProvider and internalExecutorProvider must be specified or unspecified.");
            }
            this.createdExecutorProviders = externalExecutorProvider == null;
            this.createdScheduledProviders = scheduledExecutorProvider == null;
            this.createdLookupProviders = lookupExecutorProvider == null;
            eventLoopGroupReference = eventLoopGroup != null ? eventLoopGroup :
                    PulsarClientResourcesConfigurer.createEventLoopGroup(conf);
            this.eventLoopGroup = eventLoopGroupReference;
            this.instrumentProvider = new InstrumentProvider(conf.getOpenTelemetry());
            clientClock = conf.getClock();
            this.scheduledExecutorProvider = scheduledExecutorProvider != null ? scheduledExecutorProvider :
                    PulsarClientResourcesConfigurer.createScheduledExecutorProvider(conf);

View on GitHub (pinned to 820761864e)

Solutions

1. Set a valid service URL, e.g. conf.setServiceUrl("pulsar://broker:6650") or PulsarClient.builder().serviceUrl(...).
2. Validate the loaded configuration (non-null conf, non-blank serviceUrl) before constructing the client.
3. Check that your properties/YAML file actually contains the serviceUrl key and that it was loaded into the conf object.

Example fix

// before
ClientConfigurationData conf = new ClientConfigurationData();
PulsarClient client = new PulsarClientImpl(conf, eventLoopGroup); // blank serviceUrl
// after
conf.setServiceUrl("pulsar://localhost:6650");
PulsarClient client = new PulsarClientImpl(conf, eventLoopGroup);

if (conf == null || conf.getServiceUrl() == null || conf.getServiceUrl().isBlank()) {
    throw new IllegalArgumentException("Client configuration requires a non-blank serviceUrl");
}
new PulsarClientImpl(conf, eventLoopGroup);

try {
    client = new PulsarClientImpl(conf, eventLoopGroup);
} catch (PulsarClientException.InvalidConfigurationException e) {
    log.error("Invalid client config: serviceUrl missing/blank", e);
    throw e;
}

When it happens

Trigger: new PulsarClientImpl(conf, ...) with a null conf, or a conf built without calling serviceUrl(...), or with serviceUrl set to an empty/whitespace string.

Common situations: Building ClientConfigurationData programmatically and skipping serviceUrl; loading config from a file where the serviceUrl key is missing; passing a config object that failed to deserialize.

Related errors

• Cannot use receive() when a listener has been set
• When 'messageRoutingMode' is CustomPartition, 'messageRouter
• When 'messageRouter' is set, 'messageRoutingMode' should be
• Both externalExecutorProvider and internalExecutorProvider m
• The topic has a max partition index of %d, the number of par

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