{"record":{"id":"3fcc14ece46ea6ad","repo":"hibernate/hibernate-orm","slug":"basic-collection-has-element-type-s-which-is-no","errorCode":null,"errorMessage":"Basic collection has element type '%s' which is not a known basic type (attribute is not annotated '@ElementCollection', '@OneToMany', or '@ManyToMany')","messagePattern":"Basic collection has element type '(.+?)' which is not a known basic type \\(attribute is not annotated '@ElementCollection', '@OneToMany', or '@ManyToMany'\\)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/BasicCollectionJavaType.java","lineNumber":76,"sourceCode":"\n\tprivate final CollectionSemantics<C, E> semantics;\n\tprivate final JavaType<E> componentJavaType;\n\n\tpublic BasicCollectionJavaType(ParameterizedType type, JavaType<E> componentJavaType, CollectionSemantics<C, E> semantics) {\n\t\tsuper( type, new CollectionMutabilityPlan<>( componentJavaType, semantics ) );\n\t\tthis.semantics = semantics;\n\t\tthis.componentJavaType = componentJavaType;\n\t}\n\n\t@Override\n\tpublic JavaType<E> getElementJavaType() {\n\t\treturn componentJavaType;\n\t}\n\n\t@Override\n\tpublic JdbcType getRecommendedJdbcType(JdbcTypeIndicators indicators) {\n\t\tif ( componentJavaType instanceof UnknownBasicJavaType ) {\n\t\t\tthrow new MappingException(\"Basic collection has element type '\"\n\t\t\t\t\t+ componentJavaType.getTypeName()\n\t\t\t\t\t+ \"' which is not a known basic type\"\n\t\t\t\t\t+ \" (attribute is not annotated '@ElementCollection', '@OneToMany', or '@ManyToMany')\");\n\t\t}\n\t\t// Always determine the recommended type to make sure this is a valid basic java type\n\t\t// (even though we only use this inside the if block, we want it to throw here if something wrong)\n\t\tfinal var recommendedComponentJdbcType = componentJavaType.getRecommendedJdbcType( indicators );\n\t\tfinal var typeConfiguration = indicators.getTypeConfiguration();\n\t\treturn typeConfiguration.getJdbcTypeRegistry()\n\t\t\t\t.resolveTypeConstructorDescriptor(\n\t\t\t\t\t\tindicators.getPreferredSqlTypeCodeForArray( recommendedComponentJdbcType.getDefaultSqlTypeCode() ),\n\t\t\t\t\t\ttypeConfiguration.getBasicTypeRegistry().resolve( componentJavaType, recommendedComponentJdbcType ),\n\t\t\t\t\t\tColumnTypeInformation.EMPTY\n\t\t\t\t);\n\t}\n\n\tpublic CollectionSemantics<C, E> getSemantics() {\n\t\treturn semantics;","sourceCodeStart":58,"sourceCodeEnd":94,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/spi/BasicCollectionJavaType.java#L58-L94","documentation":"BasicCollectionJavaType models a List/Set treated as one basic value (e.g. an array-mapped column). Before choosing a JDBC type it must resolve the element type; if the element's JavaType is UnknownBasicJavaType, Hibernate has no mapping for it and bootstrap fails with this MappingException. The message itself hints the cause: the attribute probably needed @ElementCollection/@OneToMany/@ManyToMany semantics instead of basic-collection semantics.","triggerScenarios":"A collection attribute mapped as a single basic value (@JdbcTypeCode(SqlTypes.ARRAY), @Array, or plain unannotated collection) whose element type — a custom class, Object, or unresolvable generic — has no registered basic JavaType; entity-valued collections missing their relationship annotation so elements resolve as unknown basics.","commonSituations":"Forgetting @ElementCollection on a List<String>/List<enum> mapped to an array column in Hibernate 6.x; trying to persist List<OwnClass> without registering a type for OwnClass; raw collection fields without generics; annotation imports missing so @OneToMany silently does not apply.","solutions":["Add @ElementCollection to collections of basic or embeddable elements","Use @OneToMany/@ManyToMany when the elements are entities","Register a JavaType for the element class via @JavaTypeRegistration or MetadataBuilder.applyBasicType so it is no longer 'unknown'","For custom value classes, add an AttributeConverter to a supported basic type (String, int, ...) which supplies the JDBC side implicitly"],"exampleFix":"// before\n@Entity class Doc {\n    @JdbcTypeCode(SqlTypes.ARRAY)\n    @Column(name = \"tags\")\n    List<String> tags = new ArrayList<>(); // element resolves to UnknownBasicJavaType -> MappingException\n}\n\n// after\n@Entity class Doc {\n    @ElementCollection\n    @JdbcTypeCode(SqlTypes.ARRAY)\n    @Column(name = \"tags\")\n    List<String> tags = new ArrayList<>();\n}","handlingStrategy":"validation","validationCode":"static List<String> collectionFieldsMissingAnnotations(Class<?>... entities) {\n    var missing = new ArrayList<String>();\n    for (var e : entities)\n        for (var f : e.getDeclaredFields())\n            if (java.util.Collection.class.isAssignableFrom(f.getType())\n                && !f.isAnnotationPresent(jakarta.persistence.ElementCollection.class)\n                && !f.isAnnotationPresent(jakarta.persistence.OneToMany.class)\n                && !f.isAnnotationPresent(jakarta.persistence.ManyToMany.class)\n                && !f.isAnnotationPresent(jakarta.persistence.Transient.class))\n                missing.add(e.getName() + \".\" + f.getName());\n    return missing; // assert empty before buildSessionFactory()\n}","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = metadata.buildSessionFactory();\n} catch (org.hibernate.MappingException e) {\n    // message names the element type; fix the annotation or registration, then rebuild\n    throw new IllegalStateException(\"Mapping bootstrap failed: \" + e.getMessage(), e);\n}","preventionTips":["Annotate every persistent collection with @ElementCollection, @OneToMany or @ManyToMany","Always declare concrete element generics — never raw collections","Register custom element types with @JavaTypeRegistration before enabling array mapping","Bootstrap the SessionFactory in CI so mapping errors surface pre-deploy"],"tags":["hibernate","orm","mapping","element-collection","bootstrap"],"backgroundTag":"hibernate-mapping-exception","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}