apache/rocketmq · critical · IllegalStateException

The authenticationMetadataProvider is not configured.

Error message

The authenticationMetadataProvider is not configured.

What it means

IllegalStateException from the manager's lazy accessor: AuthenticationMetadataManagerImpl was built without an AuthenticationMetadataProvider, so any user operation that needs the store (create/update/delete/get/list) fails at runtime. Unlike the AuthenticationExceptions around it, this is an unrecoverable wiring error - the manager cannot function.

Source

Thrown at auth/src/main/java/org/apache/rocketmq/auth/authentication/manager/AuthenticationMetadataManagerImpl.java:211

        if (user == null) {
            throw new AuthenticationException("user can not be null");
        }
        if (StringUtils.isBlank(user.getUsername())) {
            throw new AuthenticationException("username can not be blank");
        }
        if (isCreate && StringUtils.isBlank(user.getPassword())) {
            throw new AuthenticationException("password can not be blank");
        }
    }

    private void handleException(Exception e, CompletableFuture<?> result) {
        Throwable throwable = ExceptionUtils.getRealException(e);
        result.completeExceptionally(throwable);
    }

    private AuthenticationMetadataProvider getAuthenticationMetadataProvider() {
        if (authenticationMetadataProvider == null) {
            throw new IllegalStateException("The authenticationMetadataProvider is not configured.");
        }
        return authenticationMetadataProvider;
    }

    private AuthorizationMetadataProvider getAuthorizationMetadataProvider() {
        if (authorizationMetadataProvider == null) {
            throw new IllegalStateException("The authorizationMetadataProvider is not configured.");
        }
        return authorizationMetadataProvider;
    }
}

View on GitHub (pinned to 293f588571)

Solutions

Initialize the manager through AuthenticationFactory / the standard broker wiring so the metadata provider is constructed from AuthConfig.
If embedding manually, pass a non-null AuthenticationMetadataProvider (and AuthorizationMetadataProvider) to the manager's initialization path.
Fail fast at startup: after construction, call a cheap operation (e.g. listUser) in a startup self-check so misconfiguration surfaces immediately, not on first admin call.

Example fix

// before
AuthenticationMetadataManagerImpl manager = new AuthenticationMetadataManagerImpl();
manager.createUser(user); // IllegalStateException at runtime

// after
AuthenticationMetadataManager manager = AuthenticationFactory.getMetadataManager(authConfig, metadataService);
manager.createUser(user);

Defensive patterns

Strategy: validation

Validate before calling

// Startup wiring self-check
AuthenticationMetadataManager m =
    AuthenticationFactory.getMetadataManager(authConfig, metadataService);
m.listUser(null).join(); // surfaces missing-provider wiring at boot, not at first admin call

Try / catch

catch (IllegalStateException e) { if message contains "authenticationMetadataProvider is not configured" -> abort startup with a config error; this cannot be retried at runtime. }

Prevention

Always build managers via AuthenticationFactory, never bare new
Include an auth smoke test in deployment pipelines

When it happens

Trigger: Constructing AuthenticationMetadataManagerImpl without initializing its authenticationMetadataProvider (null config / provider creation skipped) and then invoking any user-management method; typically fires inside a try block and is converted to a failed CompletableFuture by handleException.

Common situations: Custom embedding of the auth module where the manager was new'd directly instead of via AuthenticationFactory; configuration missing the metadata provider classname so init left it null; test setups that stub the manager incompletely.

Understand the failure class

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

Related errors

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