hibernate/hibernate-orm · error · MappingException

Nested arrays (with the exception of byte[][]) are not suppo

Error message

Nested arrays (with the exception of byte[][]) are not supported

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/BasicTypeRegistry.java:271

					@Override
					public int getPreferredSqlTypeCodeForArray() {
						return arrayType.getDefaultSqlTypeCode();
					}

					@Override
					public int getPreferredSqlTypeCodeForArray(int elementSqlTypeCode) {
						return arrayType.getDefaultSqlTypeCode();
					}
				}
		);
		if ( resolvedType instanceof BasicPluralType<?,?> ) {
			register( resolvedType );
		}
		else if ( resolvedType == null ) {
			if ( isNestedArray( elementType ) ) {
				// No support for nested arrays, except for byte[][]
				throw new MappingException( "Nested arrays (with the exception of byte[][]) are not supported" );
			}
		}
		return resolvedType;
	}

	private static boolean isNestedArray(BasicType<?> elementType) {
		final var elementJavaTypeClass = elementType.getJavaTypeDescriptor().getJavaTypeClass();
		return elementJavaTypeClass != null
			&& elementJavaTypeClass.isArray()
			&& elementJavaTypeClass != byte[].class;
	}

	public <J> BasicType<J> resolve(JavaType<J> javaType, JdbcType jdbcType, String baseTypeName) {
		return resolve( javaType, jdbcType, () -> new NamedBasicTypeImpl<>( javaType, jdbcType, baseTypeName ) );
	}

	/**
	 * Find an existing BasicType registration for the given JavaType and

View on GitHub (pinned to fad1729dce)

Solutions

1. 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).
2. Flatten the structure: store one row per inner array (association or element-collection), or encode as a delimited string with a custom UserType / AttributeConverter.
3. If the data is truly binary, use byte[][], the one supported nested form.
4. For read-only access to exotic DB array types, wrap access in a database view or native query instead of mapping the attribute.

Example fix

// before
@Entity
public class Grid {
    @Id Long id;
    @JdbcTypeCode(SqlTypes.ARRAY)
    @Column(columnDefinition = "text[]")
    private String[][] cells; // MappingException: nested arrays not supported
}

// after
@Entity
public class Grid {
    @Id Long id;
    @JdbcTypeCode(SqlTypes.JSON)
    @Column(columnDefinition = "jsonb")
    private String[][] cells;
}

// Reject nested-array attributes at mapping time before Hibernate type resolution
for (Field f : entityClass.getDeclaredFields()) {
    Class<?> c = f.getType();
    if (c.isArray() && c.getComponentType().isArray()
            && c.getComponentType() != byte[].class) {
        boolean jsonMapped = f.isAnnotationPresent(JdbcTypeCode.class)
            && f.getAnnotation(JdbcTypeCode.class).value() == SqlTypes.JSON;
        if (!jsonMapped) {
            throw new IllegalStateException(
                f.getName() + " is a nested array; map it as JSON or flatten it");
        }
    }
}

static boolean isSupportedArrayType(Class<?> c) {
    return c.isArray() && (!c.getComponentType().isArray()
            || c.getComponentType() == byte[].class);
}

When it happens

Trigger: 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[].

Common situations: 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.

Related errors

• Cannot parse given string into array of strings. First and l
• Cannot parse given string into array of strings. Outside of
• The INSERT statement for table [%s] contains no column, and
• cannot recreate collection while filter is enabled: " + coll
• cannot recreate collection while filter is enabled [%s : %s]

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/57e9a1307b55588d. Report an issue: GitHub.