apache/pulsar · error · IllegalArgumentException

Token Audience Claim

Error message

Token Audience Claim [${audienceClaim}] configured, but Audience stands for this broker not.

What it means

This is a configuration error thrown from AuthenticationProviderToken.initialize(). It is an IllegalArgumentException raised at broker startup when the broker configures an audienceClaim (the claim name in the token that carries the intended audience) but does not configure audience (the value identifying this broker). Without the expected audience value, the claim cannot be validated.

Solutions

1. Set tokenAudience in the broker configuration to the audience value tokens must contain (e.g. tokenAudience=pulsar)
2. Remove tokenAudienceClaim if you do not intend audience validation at all
3. Restart the broker after fixing the configuration

Example fix

# broker.conf before
tokenAudienceClaim=aud
# tokenAudience missing
// after
tokenAudienceClaim=aud
tokenAudience=pulsar

Properties props = loadBrokerConf();
if (props.containsKey("tokenAudienceClaim") && !props.containsKey("tokenAudience")) {
    throw new IllegalArgumentException("tokenAudienceClaim set but tokenAudience missing");
}

try {
    provider.initialize(config); // or startup path
} catch (IllegalArgumentException e) {
    log.fatal("Token audience configuration incomplete: {}", e.getMessage());
    throw e; // fail fast at startup
}

When it happens

Trigger: Setting tokenAudienceClaim (e.g. 'aud') in broker.conf while leaving tokenAudience unset, then initializing AuthenticationProviderToken.

Common situations: Copy-pasting only part of the token-audience config from documentation; enabling audience validation for multi-tenant token issuance but forgetting to set the broker's own audience identifier.

Related errors

• ALGORITHM_MISMATCH
• Audiences in token: [ ] not contains this broker
• auth plugin given, but authParams is empty
• Blank token found
• failed to get client token

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

Appendix: source

Thrown at pulsar-broker-common/src/main/java/org/apache/pulsar/broker/authentication/AuthenticationProviderToken.java:148

        this.confTokenAudienceSettingName = prefix + CONF_TOKEN_AUDIENCE;
        this.confTokenAllowedClockSkewSecondsSettingName = prefix + CONF_TOKEN_ALLOWED_CLOCK_SKEW_SECONDS;

        // we need to fetch the algorithm before we fetch the key
        this.publicKeyAlg = getPublicKeyAlgType(config);
        this.validationKey = getValidationKey(config);
        this.roleClaim = getTokenRoleClaim(config);
        this.audienceClaim = getTokenAudienceClaim(config);
        this.audience = getTokenAudience(config);

        long allowedSkew = getConfTokenAllowedClockSkewSeconds(config);

        this.parser = Jwts.parser()
                .setAllowedClockSkewSeconds(allowedSkew)
                .setSigningKey(this.validationKey)
                .build();

        if (audienceClaim != null && audience == null) {
            throw new IllegalArgumentException("Token Audience Claim [" + audienceClaim
                    + "] configured, but Audience stands for this broker not.");
        }
    }

    @Override
    public String getAuthMethodName() {
        return TOKEN;
    }

    @Override
    public void incrementFailureMetric(Enum<?> errorCode) {
        authenticationMetricsToken.recordFailure(errorCode);
    }

    @Override
    public String authenticate(AuthenticationDataSource authData) throws AuthenticationException {
        String token;
        try {

View on GitHub (pinned to 820761864e)