jwtk/jjwt · error · RequiredTypeException

Claim '' value is too large or too small to be represented a

Error message

Claim '' value is too large or too small to be represented as a  instance (would cause numeric overflow).

What it means

When retrieving a claim with a narrower numeric type (Integer, Short, Byte), castClaimValue refuses to narrow a Long that cannot safely fit, since JSON numbers deserialized as Long could overflow the requested type. It throws RequiredTypeException rather than silently truncating.

Source

Thrown at impl/src/main/java/io/jsonwebtoken/impl/DefaultClaims.java:148

        if (value instanceof Long || value instanceof Integer || value instanceof Short || value instanceof Byte) {
            long longValue = ((Number) value).longValue();
            if (Long.class.equals(requiredType)) {
                value = longValue;
            } else if (Integer.class.equals(requiredType) && Integer.MIN_VALUE <= longValue && longValue <= Integer.MAX_VALUE) {
                value = (int) longValue;
            } else if (requiredType == Short.class && Short.MIN_VALUE <= longValue && longValue <= Short.MAX_VALUE) {
                value = (short) longValue;
            } else if (requiredType == Byte.class && Byte.MIN_VALUE <= longValue && longValue <= Byte.MAX_VALUE) {
                value = (byte) longValue;
            }
        }

        if (value instanceof Long &&
                (requiredType.equals(Integer.class) || requiredType.equals(Short.class) || requiredType.equals(Byte.class))) {
            String msg = "Claim '" + name + "' value is too large or too small to be represented as a " +
                    requiredType.getName() + " instance (would cause numeric overflow).";
            throw new RequiredTypeException(msg);
        }

        if (!requiredType.isInstance(value)) {
            throw new RequiredTypeException(String.format(CONVERSION_ERROR_MSG, value.getClass(), requiredType));
        }

        return requiredType.cast(value);
    }
}

View on GitHub (pinned to fb71496164)

Solutions

1. Request the claim as Long.class instead of a narrower type.
2. Validate the range before requesting: check the Long value fits in the target type and cast yourself.
3. Change the token producer so the claim value fits the type you read it as.
4. Catch RequiredTypeException and fall back to a wider numeric retrieval.

Example fix

// before
Integer iat = claims.get("iat", Integer.class); // overflow risk
// after
Long iat = claims.get("iat", Long.class);

Object v = claims.get(name);
if (v instanceof Long l && (l > Integer.MAX_VALUE || l < Integer.MIN_VALUE)) { /* use Long */ }

try { return claims.get(name, Integer.class); } catch (RequiredTypeException e) { return claims.get(name, Long.class); }

When it happens

Trigger: Calling claims.get("claimName", Integer.class) (or Short.class/Byte.class) where the parsed claim value is a Long whose magnitude exceeds the target type's range.

Common situations: Large epoch-second timestamps or big counters requested as Integer; code assuming claims are ints after a library upgrade; tokens from producers using very large numeric values.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

• Cannot convert existing claim value of type '%s' to desired
• Unexpected Claims JWS.
• Unexpected Claims JWE.
• Cannot create Date from '' value ''. Cause:
• Unexpected unsecured Claims JWT.

AI-assisted analysis of jwtk/jjwt@fb71496164 (2026-09-09). Data as JSON: /api/errors/9cb01de6ffb2b39c. Report an issue: GitHub.