apache/rocketmq · critical · AuthenticationException

The authenticationMetadataProvider is not configured

Error message

The authenticationMetadataProvider is not configured

What it means

DefaultAuthenticationHandler was constructed but AuthenticationFactory.getMetadataProvider(config, metadataService) returned null, so there is no backend to look up users. The handler explicitly refuses to authenticate without a metadata provider rather than failing open. This is a server-side wiring/configuration error, not a client error.

Source

Thrown at auth/src/main/java/org/apache/rocketmq/auth/authentication/chain/DefaultAuthenticationHandler.java:50

import org.apache.rocketmq.common.chain.HandlerChain;

public class DefaultAuthenticationHandler implements Handler<DefaultAuthenticationContext, CompletableFuture<Void>> {

    private final AuthenticationMetadataProvider authenticationMetadataProvider;

    public DefaultAuthenticationHandler(AuthConfig config, Supplier<?> metadataService) {
        this.authenticationMetadataProvider = AuthenticationFactory.getMetadataProvider(config, metadataService);
    }

    @Override
    public CompletableFuture<Void> handle(DefaultAuthenticationContext context,
        HandlerChain<DefaultAuthenticationContext, CompletableFuture<Void>> chain) {
        return getUser(context).thenAccept(user -> doAuthenticate(context, user));
    }

    protected CompletableFuture<User> getUser(DefaultAuthenticationContext context) {
        if (this.authenticationMetadataProvider == null) {
            throw new AuthenticationException("The authenticationMetadataProvider is not configured");
        }
        if (StringUtils.isEmpty(context.getUsername())) {
            throw new AuthenticationException("username cannot be null.");
        }
        return this.authenticationMetadataProvider.getUser(context.getUsername());
    }

    protected void doAuthenticate(DefaultAuthenticationContext context, User user) {
        if (user == null) {
            throw new AuthenticationException("User:{} is not found.", context.getUsername());
        }
        if (user.getUserStatus() == UserStatus.DISABLE) {
            throw new AuthenticationException("User:{} is disabled.", context.getUsername());
        }
        String signature = AclSigner.calSignature(context.getContent(), user.getPassword());
        if (context.getSignature() == null
            || !MessageDigest.isEqual(signature.getBytes(AclSigner.DEFAULT_CHARSET), context.getSignature().getBytes(AclSigner.DEFAULT_CHARSET))) {
            throw new AuthenticationException("check signature failed.");

View on GitHub (pinned to 293f588571)

Solutions

1. Check broker/proxy logs at startup: this usually surfaces the underlying reason getMetadataProvider returned null (ClassNotFound / instantiation failure).
2. Correct the auth configuration so the metadata provider is resolvable, e.g. set authenticationMetadataProvider to the shipped implementation (org.apache.rocketmq.auth.metadata.manager.AuthenticationMetadataManagerImpl or the declared provider class) and ensure its required datastore (radius/jute KV or database) is reachable.
3. Ensure the auth jar and its dependencies are on the server classpath and versions match the broker.

Example fix

// before (broker.conf)
authenticationEnabled=true
# no authenticationMetadataProvider configured

// after (broker.conf)
authenticationEnabled=true
authenticationMetadataProvider=org.apache.rocketmq.auth.metadata.manager.AuthenticationMetadataManagerImpl
authConfig=... # datastore config the provider needs

// Server-side startup self-check (broker/proxy bootstrap)
if (authConfig.isAuthenticationEnabled()) {
    AuthenticationHandler handler = AuthenticationFactory.getAuthenticationHandler(authConfig, metadataService);
    // constructing/invoking it at startup surfaces provider misconfig immediately
}

This is server-side and non-retryable: catch at broker startup, log the underlying provider-resolution failure, and refuse to start with auth enabled.

When it happens

Trigger: Broker/proxy starts with authentication enabled (e.g. authenticationEnabled=true) but the configured metadata provider class cannot be instantiated - wrong className in config, missing auth implementation jar on the classpath, or metadataService supplier incompatible with the provider constructor.

Common situations: auth module version mismatch where the configured authMetadataProvider classname does not exist; deploying the distribution without the auth jar; typos in the provider config key; upgrading RocketMQ and the provider class moved packages.

Understand the failure class

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

Related errors

• The authenticationMetadataProvider is not configured.
• datetime is null.
• authentication header is incorrect.
• authentication keyValues length is incorrect, actual length=
• authentication credential length is incorrect, actual length

AI-assisted analysis of apache/rocketmq@293f588571 (2026-08-14). Data as JSON: /api/errors/4dbe640ba354aa42. Report an issue: GitHub.