hibernate/hibernate-orm · error · UncheckedIOException

Error serializing entity

Error message

Error serializing entity

What it means

DescriptiveJsonGeneratingVisitor, used by Hibernate Assistant tooling to render query results as descriptive JSON, wraps any IOException from the underlying JsonDocumentWriter in an UncheckedIOException while serializing an entity (identifier plus properties). It signals that the writer stream failed mid-entity, not that the entity mapping is invalid.

Source

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

	private Map<String, IdentitySet<Object>> circularityTracker;

	@Override
	protected void serializeEntity(Object value, EntityMappingType entityType, WrapperOptions options, JsonDocumentWriter writer) {
		final EntityIdentifierMapping identifierMapping = entityType.getIdentifierMapping();
		trackingEntity( value, entityType, shouldProcessEntity -> {
			try {
				writer.startObject();
				writer.objectKey( identifierMapping.getAttributeName() );
				serializeEntityIdentifier( value, identifierMapping, options, writer );
				if ( shouldProcessEntity ) {
					// if it wasn't already encountered, append all properties
					serializeObjectValues( entityType, value, options, writer );
				}
				writer.endObject();
			}
			catch (IOException e) {
				throw new UncheckedIOException( "Error serializing entity", e );
			}
		} );
	}

	private void trackingEntity(Object entity, EntityMappingType entityType, Consumer<Boolean> action) {
		if ( circularityTracker == null ) {
			circularityTracker = new HashMap<>();
		}
		final IdentitySet<Object> entities = circularityTracker.computeIfAbsent(
				entityType.getEntityName(),
				k -> new IdentitySet<>()
		);
		final boolean added = entities.add( entity );
		action.accept( added );
		if ( added ) {
			entities.remove( entity );
		}
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Check the writer/stream lifecycle: do not close the sink before serialization completes.
2. Catch UncheckedIOException in the tooling integration and retry with a fresh writer.
3. Reduce the serialized graph (projection instead of full entities) if size triggers the failure.

try {
    return resultsJsonSerializer.toJson(resultList);
} catch (UncheckedIOException ex) {
    if ("Error serializing entity".equals(ex.getMessage())) {
        // writer/stream failed mid-entity: report partial failure, retry with fresh writer
        return retryWithFreshWriter(resultList, ex);
    }
    throw ex;
}

When it happens

Trigger: Serializing a query result entity to descriptive JSON when the writer's target stream throws: a closed writer, an IO error on the underlying sink, or a custom JsonDocumentWriter implementation failing inside startObject/objectKey/endObject calls.

Common situations: Tooling integrations (Hibernate Assistant result export) writing to streams with lifecycle bugs; very large object graphs exhausting buffers; interleaved close() calls during result rendering.

Related errors

• Support for model part type not yet implemented:
• Failed to serialize JSON mapping
• Could not serialize array element
• Unsupported numeric type: {}
• array case should be treated at upper level

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