{"record":{"id":"c9b10ab0eae90752","repo":"jwtk/jjwt","slug":"cannot-convert-existing-claim-value-of-type-s-t","errorCode":null,"errorMessage":"Cannot convert existing claim value of type '%s' to desired type '%s'. JJWT only converts simple String, Date, Long, Integer, Short and Byte types automatically. Anything more complex is expected to be already converted to your desired type by the JSON Deserializer implementation. You may specify a custom Deserializer for a JwtParser with the desired conversion configuration via the JwtParserBuilder.deserializer() method. See https://github.com/jwtk/jjwt#custom-json-processor for more information. If using Jackson, you can specify custom claim POJO types as described in https://github.com/jwtk/jjwt#json-jackson-custom-types","messagePattern":"Cannot convert existing claim value of type '%s' to desired type '%s'\\. JJWT only converts simple String, Date, Long, Integer, Short and Byte types automatically\\. Anything more complex is expected to be already converted to your desired type by the JSON Deserializer implementation\\. You may specify a custom Deserializer for a JwtParser with the desired conversion configuration via the JwtParserBuilder\\.deserializer\\(\\) method\\. See https://github\\.com/jwtk/jjwt#custom-json-processor for more information\\. If using Jackson, you can specify custom claim POJO types as described in https://github\\.com/jwtk/jjwt#json-jackson-custom-types","errorType":"exception","errorClass":"RequiredTypeException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/DefaultClaims.java","lineNumber":152,"sourceCode":"                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":134,"sourceCodeEnd":158,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/DefaultClaims.java#L134-L158","documentation":"castClaimValue only auto-converts simple String, Date, Long, Integer, Short and Byte claim values. If the deserialized claim is of any other type (Map, List, custom POJO, Boolean, etc.) and you request an incompatible requiredType, RequiredTypeException is thrown with this guidance message.","triggerScenarios":"Calling claims.get(name, SomeType.class) where the claim deserialized as a type JJWT does not convert — e.g. a nested JSON object arriving as LinkedHashMap but requested as a custom POJO class.","commonSituations":"Reading custom claim objects from a token parsed with the default Jackson/Gson deserializer; expecting POJOs that the JSON deserializer never instantiated; type changes after migrating parsers.","solutions":["Request the claim as its natural deserialized type (e.g. Map.class) and map it to your POJO yourself.","Register a custom Deserializer via JwtParserBuilder.deserializer() configured to produce your desired types (see jjwt#json-jackson-custom-types).","Use the Jackson ObjectMapper.convertValue(map, MyPojo.class) on the raw claim value.","Catch RequiredTypeException and handle the type mismatch explicitly."],"exampleFix":"// before\nUser user = claims.get(\"user\", User.class); // RequiredTypeException\n// after\nMap<String, Object> map = claims.get(\"user\", Map.class);\nUser user = objectMapper.convertValue(map, User.class);","handlingStrategy":"type-guard","validationCode":"Object v = claims.get(name);\nif (v != null && !requiredType.isInstance(v)) { /* convert manually or configure deserializer */ }","typeGuard":"<T> T claimAs(Claims c, String name, Class<T> type) { Object v = c.get(name); return type.isInstance(v) ? type.cast(v) : null; }","tryCatchPattern":"try { return claims.get(name, MyPojo.class); } catch (RequiredTypeException e) { Map<String,Object> m = claims.get(name, Map.class); return objectMapper.convertValue(m, MyPojo.class); }","preventionTips":["Configure a custom Deserializer (JwtParserBuilder.deserializer()) for POJO claims","Know your deserializer's default types (Map/List for nested JSON)","Convert raw Map/List values explicitly with ObjectMapper.convertValue"],"tags":["jwt","claims","type-conversion","deserialization"],"backgroundTag":"type-mismatch","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"}