hibernate/hibernate-orm · error · EnhancementException

Unable to perform extended enhancement - Unable to locate [%

Error message

Unable to perform extended enhancement - Unable to locate [%s]

What it means

With extended (inter-method) enhancement enabled, FieldAccessEnhancer rewrites field accesses from ANY method of the class (not just accessors). For each owner type referenced by a field instruction it must resolve the TypeDescription via classPool.describe; if the resolution does not resolve (after cleaning '/' to '.'), it throws EnhancementException('Unable to perform extended enhancement - Unable to locate [<type>]') - the type is simply not visible to the enhancer's class pool.

Source

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

										false
								);
								return;
							default:
								throw new EnhancementException( "Unexpected opcode: " + opcode );
						}
					}
					super.visitFieldInsn( opcode, owner, name, desc );
				}
			}
		};
	}

	private TypeDescription findDeclaredType(String name) {
		//Classpool#describe does not accept '/' in the description name as it expects a class name
		final String cleanedName = name.replace( '/', '.' );
		final var resolution = classPool.describe( cleanedName );
		if ( !resolution.isResolved() ) {
			throw new EnhancementException( String.format(
					"Unable to perform extended enhancement - Unable to locate [%s]",
					cleanedName
			) );
		}
		return resolution.resolve();
	}

	private AnnotatedFieldDescription findField(TypeDescription declaredOwnedType, String name, String desc) {
		final var fields = findFields( declaredOwnedType, name, desc );
		if ( fields.size() != 1 ) {
			throw new EnhancementException( String.format(
					"Unable to perform extended enhancement - No unique field [%s] defined by [%s]",
					name,
					declaredOwnedType.getName()
			) );
		}
		return new AnnotatedFieldDescription( enhancementContext, fields.getOnly() );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Disable extended enhancement (keep it false unless you specifically need it) - plain accessor enhancement does not need to resolve arbitrary owners.
2. Add the missing type named in the message to the enhancement plugin's classpath (it prints cleanedName with dots).
3. Reorder build tasks so generated/dependent classes exist before enhancement (enhance after compileJava of all contributing source sets).
4. Upgrade hibernate-core if the missing type is a JDK type the bundled Byte Buddy should resolve.

Example fix

// before
enhancementContext = new ByteBuddyEnhancementContext( context, true ); // extended enhancement on
// entity method references Helper.VALUE; Helper not on plugin classpath -> 'Unable to locate [com.acme.Helper]'

// after
enhancementContext = new ByteBuddyEnhancementContext( context, false ); // or add Helper to the classpath

// pre-flight for extended enhancement: every owner type referenced via field instructions must resolve
static boolean allOwnersResolvable(org.hibernate.bytecode.enhance.internal.bytebuddy.EnhancerImpl unused, ClassLoader cl, List<String> ownerTypes) {
    for ( String owner : ownerTypes ) {
        try { Class.forName( owner.replace( '/', '.' ), false, cl ); }
        catch ( ClassNotFoundException e ) { return false; }
    }
    return true;
}

When it happens

Trigger: enableExtendedEnhancement(true) on a class whose methods read fields of a type missing from the enhancement classpath: helper classes, generated classes only present at runtime, or classes from undeclared dependencies.

Common situations: Turning on extended enhancement because lazy loading inside equals/toString/helpers was needed, in a build whose enhancement classpath lacks the full dependency set; referencing constants or fields of generated sources not compiled before enhancement runs.

Related errors

• Failed to discover types for class {className}
• Unable to perform extended enhancement - No unique field [%s
• Error calling Value#setTypeUsingReflection: containingClassN
• Multiple active MetadataBuilder definitions were discovered
• Unable to determine JAR Url from <url>. Cause: <cause>

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