{"record":{"id":"9cb01de6ffb2b39c","repo":"jwtk/jjwt","slug":"claim-value-is-too-large-or-too-small-to-be-rep","errorCode":null,"errorMessage":"Claim '' value is too large or too small to be represented as a  instance (would cause numeric overflow).","messagePattern":"Claim '' value is too large or too small to be represented as a  instance \\(would cause numeric overflow\\)\\.","errorType":"exception","errorClass":"RequiredTypeException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/DefaultClaims.java","lineNumber":148,"sourceCode":"\n        if (value instanceof Long || value instanceof Integer || value instanceof Short || value instanceof Byte) {\n            long longValue = ((Number) value).longValue();\n            if (Long.class.equals(requiredType)) {\n                value = longValue;\n            } else if (Integer.class.equals(requiredType) && Integer.MIN_VALUE <= longValue && longValue <= Integer.MAX_VALUE) {\n                value = (int) longValue;\n            } else if (requiredType == Short.class && Short.MIN_VALUE <= longValue && longValue <= Short.MAX_VALUE) {\n                value = (short) longValue;\n            } else if (requiredType == Byte.class && Byte.MIN_VALUE <= longValue && longValue <= Byte.MAX_VALUE) {\n                value = (byte) longValue;\n            }\n        }\n\n        if (value instanceof Long &&\n                (requiredType.equals(Integer.class) || requiredType.equals(Short.class) || requiredType.equals(Byte.class))) {\n            String msg = \"Claim '\" + name + \"' value is too large or too small to be represented as a \" +\n                    requiredType.getName() + \" instance (would cause numeric overflow).\";\n            throw new RequiredTypeException(msg);\n        }\n\n        if (!requiredType.isInstance(value)) {\n            throw new RequiredTypeException(String.format(CONVERSION_ERROR_MSG, value.getClass(), requiredType));\n        }\n\n        return requiredType.cast(value);\n    }\n}\n","sourceCodeStart":130,"sourceCodeEnd":158,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/DefaultClaims.java#L130-L158","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Request the claim as Long.class instead of a narrower type.","Validate the range before requesting: check the Long value fits in the target type and cast yourself.","Change the token producer so the claim value fits the type you read it as.","Catch RequiredTypeException and fall back to a wider numeric retrieval."],"exampleFix":"// before\nInteger iat = claims.get(\"iat\", Integer.class); // overflow risk\n// after\nLong iat = claims.get(\"iat\", Long.class);","handlingStrategy":"try-catch","validationCode":"Object v = claims.get(name);\nif (v instanceof Long l && (l > Integer.MAX_VALUE || l < Integer.MIN_VALUE)) { /* use Long */ }","typeGuard":null,"tryCatchPattern":"try { return claims.get(name, Integer.class); } catch (RequiredTypeException e) { return claims.get(name, Long.class); }","preventionTips":["Read numeric claims as Long (the JSON default) and narrow yourself","Never assume timestamps fit in Integer","Validate claim ranges at token-validation time"],"tags":["jwt","claims","numeric-overflow","type-conversion"],"backgroundTag":"value-out-of-range","analyzedSha":"fb71496164c71442d08adec4571d9616ed5e1b8d","analyzedAt":"2026-09-09T00:33:09.982Z","contentChangedAt":"2026-09-09T00:33:09.982Z","schemaVersion":2},"datasetVersion":"2026-09-14T05:17:10.506Z"}