hibernate/hibernate-orm · error · IllegalArgumentException

Could not serialize array element

Error message

Could not serialize array element

What it means

JsonGeneratingVisitor serializes JSON aggregates, including arrays of embeddables. In the Java-array branch it visits each element; if the write throws IOException, it wraps the failure as IllegalArgumentException 'Could not serialize array element'. The original IOException is attached as the cause.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/type/descriptor/jdbc/spi/JsonGeneratingVisitor.java:82

			visitBasicPluralValues( elementJavaType, elementJdbcType, values, options, writer );
		}
		writer.endArray();
	}

	private void visitPluralAggregateValues(
			AggregateJdbcType elementJdbcType,
			Object values,
			WrapperOptions options,
			JsonDocumentWriter writer) {
		final EmbeddableMappingType embeddableMappingType = elementJdbcType.getEmbeddableMappingType();
		if ( values.getClass().isArray() ) {
			final var length = Array.getLength( values );
			for ( int j = 0; j < length; j++ ) {
				try {
					visit( embeddableMappingType, Array.get( values, j ), options, writer );
				}
				catch (IOException e) {
					throw new IllegalArgumentException( "Could not serialize array element", e );
				}
			}
		}
		else if ( values instanceof Collection<?> collection ) {
			for ( final var item : collection ) {
				try {
					visit( embeddableMappingType, item, options, writer );
				}
				catch (IOException e) {
					throw new IllegalArgumentException( "Could not serialize array element", e );
				}
			}
		}
		else {
			throw new IllegalArgumentException(
					"Expected array or collection value, but got: " + values.getClass().getName()
			);
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Inspect the caused-by IOException to find the real sink failure and fix the writer lifecycle.
2. Keep the writer open for the whole serialization call; never share it across threads.
3. Shrink the aggregate array or bind parameters instead of literals for very large values.

try {
    session.persist(order); // binds JSON aggregate with embeddable array
} catch (IllegalArgumentException ex) {
    if ("Could not serialize array element".equals(ex.getMessage()) && ex.getCause() instanceof IOException) {
        throw new DataAccessException("JSON writer failed on aggregate array", ex.getCause());
    }
    throw ex;
}

When it happens

Trigger: Writing a JSON aggregate (JsonJdbcType / Oracle OSon path) that contains an array of embeddables, when the underlying JsonDocumentWriter fails mid-element - stream error, closed writer, or a failing nested value write.

Common situations: Custom JsonDocumentWriter sinks with lifecycle bugs; binding large aggregate arrays as query literals; OSon/JSON dialect types with writer constraints.

Related errors

• Expected array or collection value, but got:
• Failed to serialize JSON mapping
• Error serializing entity
• Support for model part type not yet implemented:
• Unsupported numeric type: {}

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