hibernate/hibernate-orm · error · PersistenceException

[persistence unit: %s] Enhancement requires a temp class loa

Error message

[persistence unit: %s] Enhancement requires a temp class loader, but none was given

What it means

When runtime enhancement settings (hibernate.enhancer.enableDirtyTracking, enableLazyInitialization, enableAssociationManagement) are enabled, HibernatePersistenceProvider needs a temporary class loader to run the enhancer and asks PersistenceUnitInfo.getNewTempClassLoader() for it. Outside a full EE container that method commonly returns null, and bootstrap fails immediately with this PersistenceException naming the persistence unit.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/jpa/HibernatePersistenceProvider.java:319

				ENHANCER_ENABLE_ASSOCIATION_MANAGEMENT,
				integrationSettings,
				persistenceUnit,
				false
		);

		if ( !lazyInitializationEnabled ) {
			//noinspection removal
			DEPRECATION_LOGGER.deprecatedSettingForRemoval( ENHANCER_ENABLE_LAZY_INITIALIZATION, "true" );
		}
		if ( !dirtyTrackingEnabled ) {
			//noinspection removal
			DEPRECATION_LOGGER.deprecatedSettingForRemoval( ENHANCER_ENABLE_DIRTY_TRACKING, "true" );
		}

		if ( dirtyTrackingEnabled || lazyInitializationEnabled || associationManagementEnabled ) {
			final var classLoader = persistenceUnit.getNewTempClassLoader();
			if ( classLoader == null ) {
				throw new PersistenceException( String.format( Locale.ROOT,
						"[persistence unit: %s] Enhancement requires a temp class loader, but none was given",
						persistenceUnit.getPersistenceUnitName()
				) );
			}

			final var enhancementContext = createEnhancementContext(
					dirtyTrackingEnabled,
					lazyInitializationEnabled,
					associationManagementEnabled,
					integrationSettings,
					persistenceUnit
			);

			final EnhancingClassTransformerImpl classTransformer =
					new EnhancingClassTransformerImpl( enhancementContext );

			// NOTE : the ClassTransformer method is called discoverType, but in reality it
			// pre-enhances the classes...

View on GitHub (pinned to fad1729dce)

Solutions

Enhance at build time with the Hibernate Gradle/Maven enhancement plugin and set the three hibernate.enhancer.enable* settings to false
Or return a real throwaway ClassLoader from getNewTempClassLoader() in your PersistenceUnitInfo (EE containers do this)
If you do not need enhancement features, explicitly set all three settings to false to opt out

Example fix

// before
// enhancer settings left enabled, container returns null temp classloader -> PersistenceException

// after
props.put("hibernate.enhancer.enableDirtyTracking", "false");
props.put("hibernate.enhancer.enableLazyInitialization", "false");
props.put("hibernate.enhancer.enableAssociationManagement", "false");
// run the Hibernate enhancement plugin at build time instead

Defensive patterns

Strategy: validation

Validate before calling

// Opt out of runtime enhancement; enhance at build time instead
props.put("hibernate.enhancer.enableDirtyTracking", "false");
props.put("hibernate.enhancer.enableLazyInitialization", "false");
props.put("hibernate.enhancer.enableAssociationManagement", "false");

Prevention

Prefer build-time enhancement via the Hibernate Gradle/Maven plugin
If you enable runtime enhancement, ensure PersistenceUnitInfo.getNewTempClassLoader() returns a real classloader
Add an integration test that bootstraps the EMF in the target container

When it happens

Trigger: Java SE bootstrap or a plain Spring/Quarkus-like container whose PersistenceUnitInfo implementation returns null from getNewTempClassLoader(), while any of the three hibernate.enhancer.enable* settings is true (defaults are enabled, so merely setting one to true or leaving defaults active in such a container is enough).

Common situations: Migrating an EE app to Spring Boot without also moving enhancement to build time; custom PersistenceUnitInfo implementations that only implement getClassLoader; enabling association management at runtime for convenience in tests.

Related errors

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