lcobucci/jwt · error · Lcobucci\JWT\Token\InvalidTokenStructure

The JWT string is missing the Claim part

Error message

The JWT string is missing the Claim part

What it means

Parser::parse() requires the second JWT segment (the Base64Url-encoded claims/payload) to be non-empty. When it is empty, InvalidTokenStructure::missingClaimsPart() is thrown. A JWT shaped 'header..signature' is structurally invalid.

Solutions

1. Obtain the token from the authoritative issuer rather than reconstructing it manually
2. Validate token shape before parsing with a regex like /^[^\s.]+\.[^\s.]+\.[^\s.]+$/
3. Catch InvalidTokenStructure and return a 401 'malformed token' response
4. Check the storage/transport path for truncation (DB column size, header size limits)

Example fix

// before
$token = $parser->parse($jwt);
// after
if (!preg_match('/^[^\.]+\.[^\.]+\.[^\.]+$/', $jwt)) {
    throw new InvalidArgumentException('Malformed JWT: missing parts');
}
$token = $parser->parse($jwt);

$parts = explode('.', $jwt); if (count($parts) !== 3 || $parts[1] === '') { throw new InvalidArgumentException('JWT claims missing'); }

try { $token = $parser->parse($jwt); } catch (Lcobucci\JWT\InvalidTokenStructure $e) { return error_401('Malformed token'); }

When it happens

Trigger: Calling parse('header..signature') — e.g. a token built with an empty payload or corrupted so the claims section was removed.

Common situations: Truncated tokens from log scraping; tokens mangled by systems that strip empty segments; hand-assembled tokens in tests; copying only header and signature.

Understand the failure class

Background: "Invalid ... format", "must be in format X", "does not look like a ..." — invalid argument format errors across CLI tools and libraries — this error's family across 17 libraries.

Related errors

• The JWT string is missing the Header part
• The JWT string must have two dots
• The JWT string is missing the Signature part
• headers must be an array with non-empty-string keys
• 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/418306ced987a806. Report an issue: GitHub.

Appendix: source

Thrown at src/Token/Parser.php:35

final readonly class Parser implements ParserInterface
{
    private const int MICROSECOND_PRECISION = 6;

    public function __construct(private Decoder $decoder)
    {
    }

    public function parse(string $jwt): TokenInterface
    {
        [$encodedHeaders, $encodedClaims, $encodedSignature] = $this->splitJwt($jwt);

        if ($encodedHeaders === '') {
            throw InvalidTokenStructure::missingHeaderPart();
        }

        if ($encodedClaims === '') {
            throw InvalidTokenStructure::missingClaimsPart();
        }

        if ($encodedSignature === '') {
            throw InvalidTokenStructure::missingSignaturePart();
        }

        $header = $this->parseHeader($encodedHeaders);

        return new Plain(
            new DataSet($header, $encodedHeaders),
            new DataSet($this->parseClaims($encodedClaims), $encodedClaims),
            $this->parseSignature($encodedSignature),
        );
    }

    /**
     * Splits the JWT string into an array
     *

View on GitHub (pinned to 375813049c)