lcobucci/jwt · error · Lcobucci\JWT\Validation\ConstraintViolation

The claim " " does not have the expected value

Error message

The claim "{claim}" does not have the expected value

What it means

The claim exists but its value is not identical (===) to the expected value supplied to HasClaimWithValue, so it throws ConstraintViolation 'The claim "..." does not have the expected value'. Comparison is strict, so type differences (e.g. int 1 vs string "1") also trigger it.

Solutions

1. Align the expected value (and its PHP type) with what the issuer actually encodes
2. Fix the issuer configuration so it emits the correct value
3. Loosen to a manual comparison (==) or normalize types before validating if strict identity is undesired

Example fix

// before
new HasClaimWithValue('role', 'admin'); // token has "role": "Admin"
// after
new HasClaimWithValue('role', 'Admin'); // match issuer casing/value exactly

$actual = $token->claims()->get('role');
if ($actual !== 'admin') { /* expected value/type mismatch */ }

try {
    $validator->assert($token, new HasClaimWithValue('role', 'admin'));
} catch (RequiredConstraintsViolated $e) {
    // value mismatch; deny authorization
}

When it happens

Trigger: (new HasClaimWithValue('role', 'admin'))->assert($token) where claims contain role='user' or role=123 vs '123' (strict inequality).

Common situations: Role/permission drift between token issuance and authorization checks; scalar type mismatches (JSON numbers vs strings) between issuer and validator; multi-environment token differences.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• The token does not have the claim
• The token does not have the claim
• No constraint given.
• Builder#withClaim() is meant to be used for non-registered…
• claims must be an array with non-empty-string keys

AI-assisted analysis of lcobucci/jwt@375813049c (2026-09-14). Data as JSON: /api/errors/08abea37fff172e7. Report an issue: GitHub.

Appendix: source

Thrown at src/Validation/Constraint/HasClaimWithValue.php:36

        if (in_array($claim, Token\RegisteredClaims::ALL, true)) {
            throw CannotValidateARegisteredClaim::create($claim);
        }
    }

    public function assert(Token $token): void
    {
        if (! $token instanceof UnencryptedToken) {
            throw ConstraintViolation::error('You should pass a plain token', $this);
        }

        $claims = $token->claims();

        if (! $claims->has($this->claim)) {
            throw ConstraintViolation::error('The token does not have the claim "' . $this->claim . '"', $this);
        }

        if ($claims->get($this->claim) !== $this->expectedValue) {
            throw ConstraintViolation::error(
                'The claim "' . $this->claim . '" does not have the expected value',
                $this,
            );
        }
    }
}

View on GitHub (pinned to 375813049c)