lcobucci/jwt · error · ConstraintViolation

The token is not related to the expected subject

Error message

The token is not related to the expected subject

What it means

Thrown by the RelatedTo constraint when the token's sub (subject) claim does not equal the subject configured in the constraint. It fires during assert() when Token::isRelatedTo() returns false, meaning the token is not associated with the expected subject (e.g. the authenticated user or resource owner).

Solutions

1. Configure the RelatedTo constraint with the subject identifier that matches the token's sub claim (e.g. the current user's ID)
2. If you are the issuer, ensure the sub claim is populated with the intended subject when minting the token
3. Verify the token belongs to the requester before acting on it; otherwise reject it as potentially misused

When it happens

Trigger: Thrown at src/Validation/Constraint/RelatedTo.php:20 when the library encounters an invalid state.

Common situations: See trigger scenarios.

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

Appendix: source

Thrown at src/Validation/Constraint/RelatedTo.php:20

declare(strict_types=1);

namespace Lcobucci\JWT\Validation\Constraint;

use Lcobucci\JWT\Token;
use Lcobucci\JWT\Validation\Constraint;
use Lcobucci\JWT\Validation\ConstraintViolation;

final readonly class RelatedTo implements Constraint
{
    /** @param non-empty-string $subject */
    public function __construct(private string $subject)
    {
    }

    public function assert(Token $token): void
    {
        if (! $token->isRelatedTo($this->subject)) {
            throw ConstraintViolation::error(
                'The token is not related to the expected subject',
                $this,
            );
        }
    }
}

View on GitHub (pinned to 375813049c)