{"record":{"id":"57e9a1307b55588d","repo":"hibernate/hibernate-orm","slug":"nested-arrays-with-the-exception-of-byte-are","errorCode":null,"errorMessage":"Nested arrays (with the exception of byte[][]) are not supported","messagePattern":"Nested arrays \\(with the exception of byte\\[\\]\\[\\]\\) are not supported","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/type/BasicTypeRegistry.java","lineNumber":271,"sourceCode":"\n\t\t\t\t\t@Override\n\t\t\t\t\tpublic int getPreferredSqlTypeCodeForArray() {\n\t\t\t\t\t\treturn arrayType.getDefaultSqlTypeCode();\n\t\t\t\t\t}\n\n\t\t\t\t\t@Override\n\t\t\t\t\tpublic int getPreferredSqlTypeCodeForArray(int elementSqlTypeCode) {\n\t\t\t\t\t\treturn arrayType.getDefaultSqlTypeCode();\n\t\t\t\t\t}\n\t\t\t\t}\n\t\t);\n\t\tif ( resolvedType instanceof BasicPluralType<?,?> ) {\n\t\t\tregister( resolvedType );\n\t\t}\n\t\telse if ( resolvedType == null ) {\n\t\t\tif ( isNestedArray( elementType ) ) {\n\t\t\t\t// No support for nested arrays, except for byte[][]\n\t\t\t\tthrow new MappingException( \"Nested arrays (with the exception of byte[][]) are not supported\" );\n\t\t\t}\n\t\t}\n\t\treturn resolvedType;\n\t}\n\n\tprivate static boolean isNestedArray(BasicType<?> elementType) {\n\t\tfinal var elementJavaTypeClass = elementType.getJavaTypeDescriptor().getJavaTypeClass();\n\t\treturn elementJavaTypeClass != null\n\t\t\t&& elementJavaTypeClass.isArray()\n\t\t\t&& elementJavaTypeClass != byte[].class;\n\t}\n\n\tpublic <J> BasicType<J> resolve(JavaType<J> javaType, JdbcType jdbcType, String baseTypeName) {\n\t\treturn resolve( javaType, jdbcType, () -> new NamedBasicTypeImpl<>( javaType, jdbcType, baseTypeName ) );\n\t}\n\n\t/**\n\t * Find an existing BasicType registration for the given JavaType and","sourceCodeStart":253,"sourceCodeEnd":289,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/type/BasicTypeRegistry.java#L253-L289","documentation":"BasicTypeRegistry.resolvedType (BasicTypeRegistry.java:215-274) builds basic array types element-wise; when the element of an array-typed attribute would itself be an array Java type, resolution returns null and Hibernate reports MappingException 'Nested arrays (with the exception of byte[][]) are not supported'. Only byte[][] is permitted (it maps to an array of VARBINARY), because a flat SQL ARRAY type cannot represent deeper nesting.","triggerScenarios":"Mapping an entity attribute of type int[][], String[][], Integer[][], List<String>[] etc. and letting Hibernate resolve a basic (SQL ARRAY) type for it - typically with @JdbcTypeCode(SqlTypes.ARRAY) or by default on dialects with array support; also resolving a custom ArrayJdbcType whose element Java type is an array other than byte[].","commonSituations":"PostgreSQL users mapping matrix/grid or coordinate-array columns (text[][]) to Java array-of-array attributes; migrating from hstore/jsonb hacks to native arrays after upgrading Hibernate 6.1+; JSON-of-arrays data models that developers try to map with nested primitive arrays.","solutions":["Map nested arrays as JSON instead: @JdbcTypeCode(SqlTypes.JSON) with a String[][] or List<List<String>> attribute (needs hibernate-dialect JSON support or a JSON mapping library).","Flatten the structure: store one row per inner array (association or element-collection), or encode as a delimited string with a custom UserType / AttributeConverter.","If the data is truly binary, use byte[][], the one supported nested form.","For read-only access to exotic DB array types, wrap access in a database view or native query instead of mapping the attribute."],"exampleFix":"// before\n@Entity\npublic class Grid {\n    @Id Long id;\n    @JdbcTypeCode(SqlTypes.ARRAY)\n    @Column(columnDefinition = \"text[]\")\n    private String[][] cells; // MappingException: nested arrays not supported\n}\n\n// after\n@Entity\npublic class Grid {\n    @Id Long id;\n    @JdbcTypeCode(SqlTypes.JSON)\n    @Column(columnDefinition = \"jsonb\")\n    private String[][] cells;\n}","handlingStrategy":"validation","validationCode":"// Reject nested-array attributes at mapping time before Hibernate type resolution\nfor (Field f : entityClass.getDeclaredFields()) {\n    Class<?> c = f.getType();\n    if (c.isArray() && c.getComponentType().isArray()\n            && c.getComponentType() != byte[].class) {\n        boolean jsonMapped = f.isAnnotationPresent(JdbcTypeCode.class)\n            && f.getAnnotation(JdbcTypeCode.class).value() == SqlTypes.JSON;\n        if (!jsonMapped) {\n            throw new IllegalStateException(\n                f.getName() + \" is a nested array; map it as JSON or flatten it\");\n        }\n    }\n}","typeGuard":"static boolean isSupportedArrayType(Class<?> c) {\n    return c.isArray() && (!c.getComponentType().isArray()\n            || c.getComponentType() == byte[].class);\n}","tryCatchPattern":null,"preventionTips":["Map matrix-like data as JSON (@JdbcTypeCode(SqlTypes.JSON)) rather than native SQL arrays.","Remember byte[][] is the only supported nested array; document this next to array-mapping conventions."],"tags":["hibernate","array-mapping","postgresql","mapping","basic-type"],"backgroundTag":"nested-array-mapping-unsupported","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}