{"record":{"id":"4f1d789b8e1ac936","repo":"jwtk/jjwt","slug":"cannot-cast-value-getclass-getname-to-col","errorCode":null,"errorMessage":"Cannot cast ${value.getClass().getName()} to ${COLLECTION_TYPE.getName()}<${IDIOMATIC_TYPE.getName()}>","messagePattern":"Cannot cast (.+?) to (.+?)<(.+?)>","errorType":"validation","errorClass":"ClassCastException","httpStatus":null,"severity":"error","filePath":"impl/src/main/java/io/jsonwebtoken/impl/lang/DefaultParameter.java","lineNumber":74,"sourceCode":"        if (value == null) {\n            return true;\n        }\n        if (COLLECTION_TYPE != null && COLLECTION_TYPE.isInstance(value)) {\n            Collection<? extends T> c = COLLECTION_TYPE.cast(value);\n            return c.isEmpty() || IDIOMATIC_TYPE.isInstance(c.iterator().next());\n        }\n        return IDIOMATIC_TYPE.isInstance(value);\n    }\n\n    @SuppressWarnings(\"unchecked\")\n    @Override\n    public T cast(Object value) {\n        if (value != null) {\n            if (COLLECTION_TYPE != null) { // parameter represents a collection, ensure it and its elements are the expected type:\n                if (!COLLECTION_TYPE.isInstance(value)) {\n                    String msg = \"Cannot cast \" + value.getClass().getName() + \" to \" +\n                            COLLECTION_TYPE.getName() + \"<\" + IDIOMATIC_TYPE.getName() + \">\";\n                    throw new ClassCastException(msg);\n                }\n                Collection<?> c = COLLECTION_TYPE.cast(value);\n                if (!c.isEmpty()) {\n                    Object element = c.iterator().next();\n                    if (!IDIOMATIC_TYPE.isInstance(element)) {\n                        String msg = \"Cannot cast \" + value.getClass().getName() + \" to \" +\n                                COLLECTION_TYPE.getName() + \"<\" + IDIOMATIC_TYPE.getName() + \">: At least one \" +\n                                \"element is not an instance of \" + IDIOMATIC_TYPE.getName();\n                        throw new ClassCastException(msg);\n                    }\n                }\n            } else if (!IDIOMATIC_TYPE.isInstance(value)) {\n                String msg = \"Cannot cast \" + value.getClass().getName() + \" to \" + IDIOMATIC_TYPE.getName();\n                throw new ClassCastException(msg);\n            }\n        }\n        return (T) value;\n    }","sourceCodeStart":56,"sourceCodeEnd":92,"githubUrl":"https://github.com/jwtk/jjwt/blob/fb71496164c71442d08adec4571d9616ed5e1b8d/impl/src/main/java/io/jsonwebtoken/impl/lang/DefaultParameter.java#L56-L92","documentation":"DefaultParameter.cast validates a value assigned to a typed JWT header/claim parameter. When the parameter is a collection type and the value is not an instance of the expected collection class (e.g. not a List/Set), a ClassCastException is thrown describing the actual vs expected types. This guards Java's type-erased collections at runtime.","triggerScenarios":"Putting a non-collection value (String, Map, array) into a claim whose parameter is declared as Collection<SomeType>, or deserializing a JWT whose claim JSON type differs from the declared parameter type.","commonSituations":"A claim normally a List<String> arriving as a single String from an external issuer; custom claim builders passing wrong types; JSON payloads where arrays got collapsed to scalars.","solutions":["Pass a properly typed collection: Arrays.asList(...), List.of(...), etc., matching COLLECTION_TYPE.","Check the JWT payload's actual JSON type for that claim and align the value or the registered Parameter type.","Wrap assignment in a conversion step that normalizes single values into a one-element list."],"exampleFix":"// before\njwt.claim(\"roles\", \"admin\"); // parameter expects Collection\n// after\njwt.claim(\"roles\", java.util.Collections.singletonList(\"admin\"));","handlingStrategy":"type-guard","validationCode":"if (!(value instanceof List) && !(value instanceof Set)) {\n    value = Collections.singletonList(value);\n}","typeGuard":"static boolean isCollectionOf(Object v, Class<?> collType, Class<?> elemType) {\n    return collType.isInstance(v)\n        && ((Collection<?>) v).stream().allMatch(elemType::isInstance);\n}","tryCatchPattern":"try {\n    param.cast(value);\n} catch (ClassCastException e) {\n    // coerce to expected collection type before retrying\n}","preventionTips":["Use typed generics (List<String>) at call sites, never raw Collections","Normalize scalar-or-array claim input into a list before assignment","Check external issuers' claim shapes against your parameter schema"],"tags":["classcast","type-mismatch","jwt-claims"],"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"}