What causes "Failed to enhance class {className}" in hibernate/hibernate-orm?

Unwrap EnhancementException.getCause() first - it names the actual Byte Buddy failure (e.g. 'Java 22 support not yet') and dictates the fix.

hibernate/hibernate-orm · error · EnhancementException

Failed to enhance class {className}

Error message

Failed to enhance class {className}

What it means

EnhancerImpl.enhance() runs Byte Buddy over the class bytes (typePool.describe(...).resolve() plus byteBuddyState.rewrite(...)) to inject the Managed-entity instrumentation. Any RuntimeException escaping that machinery - other than an already-typed EnhancementException - is rethrown as EnhancementException('Failed to enhance class <name>') with the original exception as cause. The message itself is generic; the real reason lives in the cause chain.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/EnhancerImpl.java:163

	@Override
	public byte[] enhance(String className, byte[] originalBytes) throws EnhancementException {
		//Classpool#describe does not accept '/' in the description name as it expects a class name. See HHH-12545
		final String safeClassName = className.replace( '/', '.' );
		typePool.registerClassNameAndBytes( safeClassName, originalBytes );
		try {
			final var typeDescription = typePool.describe( safeClassName ).resolve();
			return byteBuddyState.rewrite( typePool, safeClassName, byteBuddy ->
					doEnhance( () -> byteBuddy.ignore( constants.defaultFinalizer() )
									.redefine( typeDescription, typePool.asClassFileLocator() )
									.annotateType( infoAnnotationList ),
							typeDescription
					) );
		}
		catch (EnhancementException e) {
			throw e;
		}
		catch (RuntimeException e) {
			throw new EnhancementException( "Failed to enhance class " + className, e );
		}
		finally {
			typePool.deregisterClassNameAndBytes( safeClassName );
		}
	}

	@Override
	public void discoverTypes(String className, byte[] originalBytes) {
		if ( originalBytes != null ) {
			typePool.registerClassNameAndBytes( className, originalBytes );
		}
		try {
			final var typeDescription = typePool.describe( className ).resolve();
			enhancementContext.registerDiscoveredType( typeDescription, Type.PersistenceType.ENTITY );
			enhancementContext.discoverCompositeTypes( typeDescription, typePool );
		}
		catch (RuntimeException e) {
			throw new EnhancementException( "Failed to discover types for class " + className, e );

View on GitHub (pinned to fad1729dce)

Solutions

Unwrap EnhancementException.getCause() first - it names the actual Byte Buddy failure (e.g. 'Java 22 support not yet') and dictates the fix.
Upgrade hibernate-core (enhancement runs with its bundled Byte Buddy) to a release that supports your class-file version, or downgrade the compiler target.
Ensure the enhancement task's classpath contains every type the entity references (supertypes, embedded types, annotations).
As a stopgap, exclude the class from enhancement (plugin include/exclude patterns or EnhancementContext#doNotEnhance) and report it - unenhanced entities only lose lazy/dirty-tracking features.

Example fix

// before
byte[] enhanced = enhancer.enhance( "com.acme.Order", originalBytes ); // throws EnhancementException

// after
try { enhanced = enhancer.enhance( "com.acme.Order", originalBytes ); }
catch ( EnhancementException e ) { log.error( "cause:", e.getCause() ); throw e; }
// and fix the root cause, e.g. bump hibernate-core for the newer class-file version

Defensive patterns

Strategy: try-catch

Validate before calling

// fail fast when the entity class file is newer than the enhancer's Byte Buddy supports
static int classFileMajor(byte[] bytes) { return ( ( bytes[6] & 0xFF ) << 8 ) | ( bytes[7] & 0xFF ); }
static boolean supportedByThisEnhancer(byte[] bytes) { return classFileMajor( bytes ) <= 65; } // check your hibernate-core release

Try / catch

try {
    enhanced = enhancer.enhance( className, originalBytes );
}
catch ( EnhancementException e ) {
    if ( ( "Failed to enhance class " + className ).equals( e.getMessage() ) ) {
        Throwable root = e.getCause(); // real reason: unsupported class file version, resolution error, visitor bug
        diagnostics.add( className + " -> " + root );
    }
    throw e;
}

Prevention

Upgrade hibernate-core in lockstep with JDK upgrades; its bundled Byte Buddy defines which class files can be enhanced.
Keep the enhancement plugin's classpath equal to the compile+runtime classpath.
Log EnhancementException causes in the build - the wrapper message alone says nothing actionable.

When it happens

Trigger: Running the Hibernate enhancer (Maven/Gradle plugin or the Enhancer API) on a class where Byte Buddy fails: class file version newer than the Byte Buddy bundled with this Hibernate understands, unresolved supertypes/annotations in the type pool, or an internal visitor error while rewriting a construct of that class.

Common situations: Building with a brand-new JDK while hibernate-core (and its shaded Byte Buddy) is older; entity hierarchies referencing classes missing from the enhancement classpath; mapper/record/lombok-generated constructs that the enhancer of that Hibernate version cannot rewrite.

Related errors

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