hibernate/hibernate-orm · error · UnsupportedOperationException

Initialization of entity enhancement used to act like a prox

Error message

Initialization of entity enhancement used to act like a proxy is not supported by this EntityPersister : {className}

What it means

EntityPersister.initializeEnhancedEntityUsedAsProxy is invoked by EnhancementAsProxyLazinessInterceptor when a bytecode-enhanced entity acting as a lazy proxy has an attribute accessed and its non-lazy state must be loaded. The interface ships only a default implementation that throws UnsupportedOperationException; full persisters derived from AbstractEntityPersister override it, so any other EntityPersister implementation breaks on the first attribute access after load.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/persister/entity/EntityPersister.java:247

	boolean isLazy();

	int getPropertySpan();

	boolean hasPreInsertGeneratedProperties();

	boolean hasPreUpdateGeneratedProperties();

	/**
	 * Called from {@link EnhancementAsProxyLazinessInterceptor} to trigger load of
	 * the entity's non-lazy state as well as the named attribute we are accessing
	 * if it is still uninitialized after fetching non-lazy state.
	 */
	default Object initializeEnhancedEntityUsedAsProxy(
			Object entity,
			String nameOfAttributeBeingAccessed,
			SharedSessionContractImplementor session) {
		throw new UnsupportedOperationException(
				"Initialization of entity enhancement used to act like a proxy is not supported by this EntityPersister : "
						+ getClass().getName()
		);
	}

	/**
	 * Determine whether the given name represents a subclass entity
	 * (or this entity itself) of the entity mapped by this persister.
	 *
	 * @param entityName The entity name to be checked.
	 * @return True if the given entity name represents either the entity
	 * mapped by this persister or one of its subclass entities; false
	 * otherwise.
	 */
	boolean isSubclassEntityName(String entityName);

	/**
	 * Returns an array of objects that identify spaces in which properties of

View on GitHub (pinned to fad1729dce)

Solutions

Drop the custom persisterClass/@Persister override so the standard persister is used
Override initializeEnhancedEntityUsedAsProxy in the custom persister (delegate to the persister's load path)
Reconfigure enhancement to dirty-tracking only (disable enableLazyInitialization) so enhanced instances are not used as proxies

Example fix

// before: custom persister without the override + enhancement lazy-init enabled
@Entity @org.hibernate.annotations.Persister(impl = MyEntityPersister.class)
public class Customer { ... }

// after: standard persister supports enhanced-proxy initialization
@Entity
public class Customer { ... }

Defensive patterns

Strategy: type-guard

Type guard

static boolean supportsEnhancedProxyInitialization(EntityPersister persister) {
    return persister instanceof org.hibernate.persister.entity.AbstractEntityPersister;
}

Try / catch

try {
    return entity.getName(); // first attribute access on an enhanced-as-proxy instance
}
catch ( UnsupportedOperationException e ) {
    // persister without initializeEnhancedEntityUsedAsProxy support
    throw new IllegalStateException(
        "Bytecode-enhanced lazy loading is not supported by persister "
        + entity.getClass().getName(), e);
}

Prevention

Do not combine custom EntityPersister implementations with enhancement lazy-initialization
When enabling 'enableLazyInitialization' in the enhance plugin, verify every entity uses a standard persister
Keep an upgrade test that loads and touches one attribute of every entity with enhancement enabled

When it happens

Trigger: Bytecode enhancement with lazy initialization enabled (gradle/maven plugin 'enableLazyInitialization'), loading an entity, then touching any attribute while its persister is not an AbstractEntityPersister subclass — e.g., a custom persister registered via @Persister or persisterClass.

Common situations: Custom EntityPersister implementations (auditing, tenancy, sharding) written before the enhanced-proxy feature; test doubles standing in as persisters; upgrading Hibernate where this default method was added to the interface.

Related errors

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