apache/pulsar · error · IllegalStateException

Invalid proxy configuration. Authentication must be enabled

Error message

Invalid proxy configuration. Authentication must be enabled with authenticationEnabled=true when authorization is enabled with authorizationEnabled=true.

What it means

ProxyService.start enforces a startup invariant: authorization without authentication is invalid because the proxy would apply ACL checks but have no verified principal/credentials to authorize. It throws IllegalStateException at startup so the operator fixes config rather than running an insecure or nonfunctional proxy.

Source

Thrown at pulsar-proxy/src/main/java/org/apache/pulsar/proxy/server/ProxyService.java:269

                proxyConfig.getMaxConcurrentInboundConnections(),
                proxyConfig.getMaxConcurrentInboundConnectionsPerIp());

        this.openTelemetry = new PulsarProxyOpenTelemetry(proxyConfig);

        // Initialize topic list memory limiter
        this.maxTopicListInFlightLimiter = new TopicListMemoryLimiter(
                CollectorRegistry.defaultRegistry, "pulsar_proxy_", openTelemetry.getMeter(),
                proxyConfig.getMaxTopicListInFlightHeapMemSizeMB() * 1024L * 1024L,
                proxyConfig.getMaxTopicListInFlightHeapMemSizePermitsAcquireQueueSize(),
                proxyConfig.getMaxTopicListInFlightHeapMemSizePermitsAcquireTimeoutMillis(),
                proxyConfig.getMaxTopicListInFlightDirectMemSizeMB() * 1024L * 1024L,
                proxyConfig.getMaxTopicListInFlightDirectMemSizePermitsAcquireQueueSize(),
                proxyConfig.getMaxTopicListInFlightDirectMemSizePermitsAcquireTimeoutMillis());
    }

    public void start() throws Exception {
        if (proxyConfig.isAuthorizationEnabled() && !proxyConfig.isAuthenticationEnabled()) {
            throw new IllegalStateException("Invalid proxy configuration. Authentication must be enabled with "
                    + "authenticationEnabled=true when authorization is enabled with authorizationEnabled=true.");
        }

        if (!isBlank(proxyConfig.getMetadataStoreUrl()) && !isBlank(proxyConfig.getConfigurationMetadataStoreUrl())) {
            localMetadataStore = createLocalMetadataStore();
            configMetadataStore = createConfigurationMetadataStore();
            pulsarResources = new PulsarResources(localMetadataStore, configMetadataStore);
            discoveryProvider = new BrokerDiscoveryProvider(this.proxyConfig, pulsarResources);
            authorizationService = new AuthorizationService(PulsarConfigurationLoader.convertFrom(proxyConfig),
                    pulsarResources);
        }

        ServerBootstrap bootstrap = new ServerBootstrap();
        bootstrap.option(ChannelOption.SO_REUSEADDR, true);
        bootstrap.childOption(ChannelOption.ALLOCATOR, PulsarByteBufAllocator.DEFAULT);
        bootstrap.group(acceptorGroup, workerGroup);
        bootstrap.childOption(ChannelOption.TCP_NODELAY, true);
        bootstrap.childOption(ChannelOption.RCVBUF_ALLOCATOR,

View on GitHub (pinned to 820761864e)

Solutions

Set authenticationEnabled=true in the proxy configuration
Configure the required authenticationProvider* list and related provider settings for the chosen auth method
If authorization is not actually needed for the proxy, explicitly set authorizationEnabled=false instead
Restart the proxy after fixing the config and confirm start() completes without the IllegalStateException

Example fix

// before
authenticationEnabled=false
authorizationEnabled=true

// after
authenticationEnabled=true
authenticationProviders=org.apache.pulsar.broker.authentication.AuthenticationProviderToken
authorizationEnabled=true

Defensive patterns

Strategy: validation

Validate before calling

if (proxyConfig.isAuthorizationEnabled() && !proxyConfig.isAuthenticationEnabled()) {
    throw new IllegalStateException(
        "Fix config: set authenticationEnabled=true before authorizationEnabled=true");
}
proxyService.start();

Type guard

boolean canStartProxy(ProxyConfiguration cfg) {
    return !cfg.isAuthorizationEnabled() || cfg.isAuthenticationEnabled();
}

Try / catch

try {
    proxyService.start();
} catch (IllegalStateException e) {
    if (e.getMessage().contains("Authentication must be enabled")) {
        LOG.error("Proxy config invalid: enable authentication before authorization");
    }
    throw e;
}

Prevention

Always set authenticationEnabled=true together with authorizationEnabled=true in the proxy config
Document the dependency between authentication and authorization flags in runbooks
Validate proxy config in CI startup tests before deploying
When copying broker config to the proxy, keep both auth flags consistent

When it happens

Trigger: Calling proxyService.start() when proxyConfig.isAuthorizationEnabled()==true and proxyConfig.isAuthenticationEnabled()==false — i.e. properties contain authorizationEnabled=true but authenticationEnabled is absent or false.

Common situations: Operator enables authorization to lock down topics but forgets the prerequisite authentication providers config; security hardening PR turns on authorization in the proxy config file while authentication was only configured on the broker; copy of broker.properties to proxy config missing authenticationEnabled.

Understand the failure class

Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

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