{"record":{"id":"6b180d5e88e20ba5","repo":"hibernate/hibernate-orm","slug":"basic-array-has-element-type-componentjavatyp","errorCode":null,"errorMessage":"Basic array has element type '\" + componentJavaType.getTypeName() + \"' which is not a known basic type (attribute is not annotated '@ElementCollection', '@OneToMany', or '@ManyToMany')","messagePattern":"Basic array has element type '\" \\+ componentJavaType\\.getTypeName\\(\\) \\+ \"' 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/AbstractArrayJavaType.java","lineNumber":44,"sourceCode":"public abstract class AbstractArrayJavaType<T, E> extends AbstractClassJavaType<T>\n\t\timplements BasicPluralJavaType<E> {\n\n\tprivate final JavaType<E> componentJavaType;\n\n\tpublic AbstractArrayJavaType(Class<T> clazz, JavaType<E> baseDescriptor, MutabilityPlan<T> mutabilityPlan) {\n\t\tsuper( clazz, mutabilityPlan );\n\t\tthis.componentJavaType = baseDescriptor;\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 array 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\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\t@Override\n\tpublic boolean isWider(JavaType<?> javaType) {\n\t\t// Support binding single element value","sourceCodeStart":26,"sourceCodeEnd":62,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/descriptor/java/AbstractArrayJavaType.java#L26-L62","documentation":"Thrown when Hibernate must pick a JDBC type for a basic array attribute (AbstractArrayJavaType.getRecommendedJdbcType) but the element's JavaType is UnknownBasicJavaType - meaning the component class has no registered basic type. The message reminds you that non-basic element collections must be mapped as @ElementCollection/@OneToMany/@ManyToMany, not as plain arrays.","triggerScenarios":"An entity field like MyCustomType[] values or List<SomeEmbeddable> mapped as a basic array (dialect supports arrays, no collection annotations present) where the element class is not a known basic type; e.g. arrays of enums with custom mapping, arrays of Value Objects, or embeddables without @ElementCollection.","commonSituations":"Migrating to Hibernate 6/7 where basic array support was introduced and unannotated array fields stopped being treated as element collections; PostgreSQL array columns of custom types; forgetting @ElementCollection on a List<embeddable> field; element type lacking a BasicType registration.","solutions":["Annotate the field with @ElementCollection (targetClass = element type) so it is mapped as a collection, not a basic array","Change the element type to a known basic type (String, Integer, UUID, enum with @Enumerated, ...)","Register a JavaType/BasicType for the custom element class via @JavaTypeRegistration on the entity or a TypeContributor","Map the array explicitly with @JdbcTypeCode(SqlTypes.ARRAY) plus a registered element type"],"exampleFix":"// before\n@Entity\npublic class Doc {\n    private Tag[] tags; // Tag is not a known basic type -> MappingException\n}\n// after\n@Entity\npublic class Doc {\n    @ElementCollection(targetClass = String.class)\n    @Column(name = \"tags\")\n    private String[] tags;\n}\n// or: map Tag as a basic type via @JavaTypeRegistration and keep Tag[] with @JdbcTypeCode(SqlTypes.ARRAY)","handlingStrategy":"validation","validationCode":"// in a @PrePersist/@PreUpdate-free mapping test (or bootstrap check):\n// assert every array-typed persistent field has a basic element type or collection annotations\nfor (Field f : entityClass.getDeclaredFields()) {\n    Class<?> elem = f.getType().getComponentType();\n    if (elem != null && !isBasicType(elem)\n            && !f.isAnnotationPresent(ElementCollection.class)) {\n        throw new MappingException(\"Unannotated array of non-basic type: \" + f);\n    }\n}","typeGuard":"static boolean isKnownBasicElement(Class<?> c) {\n    return c.isPrimitive() || c == String.class || c.isEnum()\n        || Number.class.isAssignableFrom(c)\n        || java.time.temporal.Temporal.class.isAssignableFrom(c);\n}","tryCatchPattern":"try {\n    sessionFactory = new MetadataSources(registry).addAnnotatedClass(Doc.class)\n            .buildMetadata().buildSessionFactory();\n} catch (MappingException e) {\n    if (String.valueOf(e.getMessage()).contains(\"not a known basic type\")) {\n        // annotate as @ElementCollection or register a JavaType for the element class\n    } else throw e;\n}","preventionTips":["Always annotate plural-of-embeddable fields with @ElementCollection","Prefer List<Element> + @ElementCollection over bare arrays of custom types","Cover mappings with a bootstrap test that builds the SessionFactory in CI","Register custom element types via @JavaTypeRegistration before using them in arrays"],"tags":["hibernate","orm","jpa","array-mapping","type-mapping","mapping-exception"],"backgroundTag":"hibernate-array-element-type-unmapped","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}