{"record":{"id":"b929602b5cb1ca82","repo":"hibernate/hibernate-orm","slug":"unknown-collection","errorCode":null,"errorMessage":"Unknown collection: {}","messagePattern":"Unknown collection: (.+?)","errorType":"exception","errorClass":"UnsupportedMappingException","httpStatus":null,"severity":"critical","filePath":"hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/PluralAttributeBuilder.java","lineNumber":121,"sourceCode":"\t\t//apply loose rules\n\t\tif ( javaClass.isArray() ) {\n\t\t\treturn new ListAttributeImpl( builder );\n\t\t}\n\n\t\tif ( Map.class.isAssignableFrom( javaClass ) ) {\n\t\t\treturn new MapAttributeImpl( builder );\n\t\t}\n\t\telse if ( Set.class.isAssignableFrom( javaClass ) ) {\n\t\t\treturn new SetAttributeImpl( builder );\n\t\t}\n\t\telse if ( List.class.isAssignableFrom( javaClass ) ) {\n\t\t\treturn new ListAttributeImpl( builder );\n\t\t}\n\t\telse if ( Collection.class.isAssignableFrom( javaClass ) ) {\n\t\t\treturn new BagAttributeImpl( builder );\n\t\t}\n\n\t\tthrow new UnsupportedMappingException( \"Unknown collection: \" + attributeJtd.getJavaType() );\n\t}\n\n\tprivate static SimpleDomainType<?> determineListIndexOrMapKeyType(\n\t\t\tPluralAttributeMetadata<?,?,?> attributeMetadata,\n\t\t\tMetadataContext metadataContext) {\n\t\tfinal var javaType = attributeMetadata.getJavaType();\n\t\tif ( Map.class.isAssignableFrom( javaType ) ) {\n\t\t\treturn (SimpleDomainType<?>)\n\t\t\t\t\tdetermineSimpleType( attributeMetadata.getMapKeyValueContext(), metadataContext );\n\t\t}\n\n\t\tif ( List.class.isAssignableFrom( javaType ) || javaType.isArray() ) {\n\t\t\treturn metadataContext.getTypeConfiguration().getBasicTypeRegistry()\n\t\t\t\t\t.getRegisteredType( Integer.class );\n\t\t}\n\n\t\treturn null;\n\t}","sourceCodeStart":103,"sourceCodeEnd":139,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/metamodel/model/domain/internal/PluralAttributeBuilder.java#L103-L139","documentation":"PluralAttributeBuilder.build builds the JPA PluralAttribute for a mapped collection attribute. After strict matching (exact Map/List/Collection) and loose matching (arrays, then assignable Map/Set/List/Collection), a declared Java collection type that falls through every branch throws UnsupportedMappingException('Unknown collection: ' + javaType) at bootstrap. In practice that means a type that is not a Map/Set/List/Collection or array — most commonly a type implementing only Iterable.","triggerScenarios":"An @OneToMany/@ManyToMany/@ElementCollection attribute declared as Iterable<T>, Queue handled? (no — Queue extends Collection so it matches Bag), but Iterable<T>, or a custom collection class implementing only Iterable; an attribute whose getter returns a non-JDK-collection type due to wrong mapping on the wrong field.","commonSituations":"Domain models using Iterable for read models then annotated as associations; custom Bag/List abstractions that only extend Iterable; IDE-generated fields typed Iterable; Kotlin/Scala collection types not bridged to java.util types in mappings.","solutions":["Declare the attribute as one of java.util.Collection, List, Set, or Map (or a primitive array) — e.g. change Iterable<Order> to List<Order>","For custom collection wrappers, expose a standard JDK collection type on the mapped property and adapt elsewhere","If the type was never meant to be a persistent collection, remove the association annotation"],"exampleFix":"// before\n@OneToMany(mappedBy = \"order\", cascade = CascadeType.ALL)\nprivate Iterable<OrderLine> lines; // UnsupportedMappingException: Unknown collection\n\n// after\n@OneToMany(mappedBy = \"order\", cascade = CascadeType.ALL)\nprivate List<OrderLine> lines;","handlingStrategy":"validation","validationCode":"// Startup scan: reject association attributes whose Java type is not a mappable collection\nfor (Class<?> c : scannedEntityClasses) {\n  for (java.lang.reflect.Field f : c.getDeclaredFields()) {\n    boolean isAssociation = f.isAnnotationPresent(OneToMany.class)\n        || f.isAnnotationPresent(ManyToMany.class)\n        || f.isAnnotationPresent(ElementCollection.class);\n    if (isAssociation) {\n      Class<?> t = f.getType();\n      boolean ok = t.isArray() || Map.class.isAssignableFrom(t) || Collection.class.isAssignableFrom(t);\n      if (!ok) {\n        throw new IllegalStateException(\"Association field \" + f\n            + \" must be Map/Set/List/Collection/array, not \" + t.getName());\n      }\n    }\n  }\n}","typeGuard":"static boolean isMappableCollectionType(Class<?> t) {\n  return t.isArray() || Map.class.isAssignableFrom(t) || Collection.class.isAssignableFrom(t);\n}","tryCatchPattern":null,"preventionTips":["Declare persistent collection fields as java.util List/Set/Collection/Map — never Iterable or custom wrappers","Expose custom/read-model types only on getters of non-mapped copies, keep the mapped field standard","Run the annotation-vs-field-type scan above as a unit test over the entity package"],"tags":["hibernate","collection-mapping","metamodel","bootstrap"],"backgroundTag":"unsupported-collection-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}