{"record":{"id":"ed7ffa37cb063419","repo":"hibernate/hibernate-orm","slug":"illegal-collection-interface-type","errorCode":null,"errorMessage":"illegal collection interface type","messagePattern":"illegal collection interface type","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/Hibernate.java","lineNumber":593,"sourceCode":"\t\t\treturn (CollectionInterface<C>) list();\n\t\t}\n\t\telse if (collectionClass == Set.class) {\n\t\t\treturn (CollectionInterface<C>) set();\n\t\t}\n\t\telse if (collectionClass == Map.class) {\n\t\t\treturn (CollectionInterface<C>) map();\n\t\t}\n\t\tif (collectionClass == SortedMap.class) {\n\t\t\treturn (CollectionInterface<C>) sortedMap();\n\t\t}\n\t\telse if (collectionClass == SortedSet.class) {\n\t\t\treturn (CollectionInterface<C>) sortedSet();\n\t\t}\n\t\telse if (collectionClass == Collection.class) {\n\t\t\treturn (CollectionInterface<C>) bag();\n\t\t}\n\t\telse {\n\t\t\tthrow new IllegalArgumentException(\"illegal collection interface type\");\n\t\t}\n\t}\n\n\t/**\n\t * Obtain a {@linkplain LobHelper} for instances of {@link java.sql.Blob}\n\t * and {@link java.sql.Clob}.\n\t *\n\t * @return an instance of {@link LobHelper}\n\t *\n\t * @since 7.1\n\t */\n\tpublic static LobHelper getLobHelper() {\n\t\treturn lobHelper;\n\t}\n\n\tprivate static PersistentAttributeInterceptor getAttributeInterceptor(Object entity) {\n\t\treturn asPersistentAttributeInterceptable( entity ).$$_hibernate_getInterceptor();\n\t}","sourceCodeStart":575,"sourceCodeEnd":611,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/Hibernate.java#L575-L611","documentation":"Hibernate.collection(Class) returns a CollectionInterface factory for the six collection interfaces Hibernate knows how to instantiate persistently: List, Set, Map, SortedMap, SortedSet and Collection (bag). Passing any other Class (e.g. Queue, Deque, a custom interface, or an implementation class like ArrayList) falls through the if-chain to IllegalArgumentException('illegal collection interface type').","triggerScenarios":"Calling Hibernate.collection(Queue.class), Hibernate.collection(Deque.class) or Hibernate.collection(ArrayList.class) - i.e. any class reference that is not exactly List/Set/Map/SortedMap/SortedSet/Collection.","commonSituations":"Generic utility code that derives the collection interface from a field type or generic parameter (which may be Queue or a custom type); migrating code from Hibernate.collectionInterfaceFor-style helpers; passing implementation classes instead of interfaces.","solutions":["Pass one of the six supported interfaces: List.class, Set.class, Map.class, SortedMap.class, SortedSet.class, or Collection.class.","Map unsupported types to a supported supertype (Queue/Deque -> List or Collection) and convert when reading.","Call the specific factory directly: Hibernate.list(), Hibernate.set(), Hibernate.map(), Hibernate.sortedSet(), Hibernate.sortedMap(), Hibernate.bag().","Guard with a type check before calling (see defense) when the class comes from reflection."],"exampleFix":"// before - throws: Queue is not supported\nCollectionInterface<Queue<Task>> ci = Hibernate.collection(Queue.class);\n\n// after - map to a supported interface\nCollectionInterface<List<Task>> ci = Hibernate.collection(List.class);","handlingStrategy":"type-guard","validationCode":"private static final Set<Class<?>> SUPPORTED = Set.of(List.class, Set.class, Map.class,\n        SortedMap.class, SortedSet.class, Collection.class);\n\nif (!SUPPORTED.contains(collectionClass)) {\n    throw new IllegalArgumentException(\"Unsupported collection interface: \" + collectionClass\n            + \"; expected one of \" + SUPPORTED);\n}","typeGuard":"static boolean isSupportedCollectionInterface(Class<?> c) {\n    return c == List.class || c == Set.class || c == Map.class\n        || c == SortedMap.class || c == SortedSet.class || c == Collection.class;\n}","tryCatchPattern":"try {\n    return Hibernate.collection(collectionClass);\n} catch (IllegalArgumentException e) {\n    if (e.getMessage().equals(\"illegal collection interface type\")) {\n        return Hibernate.collection(Collection.class); // degrade to bag semantics\n    }\n    throw e;\n}","preventionTips":["Only pass the six collection interfaces Hibernate supports","When the class comes from reflection/generics, guard it with isSupportedCollectionInterface first","Use the dedicated factories (Hibernate.list(), Hibernate.set(), ...) for static call sites"],"tags":["collections","api-misuse","illegal-argument","mapping"],"backgroundTag":"unsupported-collection-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}