{"record":{"id":"13ccf7e33eeaa915","repo":"hibernate/hibernate-orm","slug":"unable-to-perform-extended-enhancement-unable-to","errorCode":null,"errorMessage":"Unable to perform extended enhancement - Unable to locate [%s]","messagePattern":"Unable to perform extended enhancement - Unable to locate \\[(.+?)\\]","errorType":"exception","errorClass":"EnhancementException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/FieldAccessEnhancer.java","lineNumber":120,"sourceCode":"\t\t\t\t\t\t\t\t\t\tfalse\n\t\t\t\t\t\t\t\t);\n\t\t\t\t\t\t\t\treturn;\n\t\t\t\t\t\t\tdefault:\n\t\t\t\t\t\t\t\tthrow new EnhancementException( \"Unexpected opcode: \" + opcode );\n\t\t\t\t\t\t}\n\t\t\t\t\t}\n\t\t\t\t\tsuper.visitFieldInsn( opcode, owner, name, desc );\n\t\t\t\t}\n\t\t\t}\n\t\t};\n\t}\n\n\tprivate TypeDescription findDeclaredType(String name) {\n\t\t//Classpool#describe does not accept '/' in the description name as it expects a class name\n\t\tfinal String cleanedName = name.replace( '/', '.' );\n\t\tfinal var resolution = classPool.describe( cleanedName );\n\t\tif ( !resolution.isResolved() ) {\n\t\t\tthrow new EnhancementException( String.format(\n\t\t\t\t\t\"Unable to perform extended enhancement - Unable to locate [%s]\",\n\t\t\t\t\tcleanedName\n\t\t\t) );\n\t\t}\n\t\treturn resolution.resolve();\n\t}\n\n\tprivate AnnotatedFieldDescription findField(TypeDescription declaredOwnedType, String name, String desc) {\n\t\tfinal var fields = findFields( declaredOwnedType, name, desc );\n\t\tif ( fields.size() != 1 ) {\n\t\t\tthrow new EnhancementException( String.format(\n\t\t\t\t\t\"Unable to perform extended enhancement - No unique field [%s] defined by [%s]\",\n\t\t\t\t\tname,\n\t\t\t\t\tdeclaredOwnedType.getName()\n\t\t\t) );\n\t\t}\n\t\treturn new AnnotatedFieldDescription( enhancementContext, fields.getOnly() );\n\t}","sourceCodeStart":102,"sourceCodeEnd":138,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/FieldAccessEnhancer.java#L102-L138","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Disable extended enhancement (keep it false unless you specifically need it) - plain accessor enhancement does not need to resolve arbitrary owners.","Add the missing type named in the message to the enhancement plugin's classpath (it prints cleanedName with dots).","Reorder build tasks so generated/dependent classes exist before enhancement (enhance after compileJava of all contributing source sets).","Upgrade hibernate-core if the missing type is a JDK type the bundled Byte Buddy should resolve."],"exampleFix":"// before\nenhancementContext = new ByteBuddyEnhancementContext( context, true ); // extended enhancement on\n// entity method references Helper.VALUE; Helper not on plugin classpath -> 'Unable to locate [com.acme.Helper]'\n\n// after\nenhancementContext = new ByteBuddyEnhancementContext( context, false ); // or add Helper to the classpath","handlingStrategy":"fallback","validationCode":"// pre-flight for extended enhancement: every owner type referenced via field instructions must resolve\nstatic boolean allOwnersResolvable(org.hibernate.bytecode.enhance.internal.bytebuddy.EnhancerImpl unused, ClassLoader cl, List<String> ownerTypes) {\n    for ( String owner : ownerTypes ) {\n        try { Class.forName( owner.replace( '/', '.' ), false, cl ); }\n        catch ( ClassNotFoundException e ) { return false; }\n    }\n    return true;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Default extended enhancement to off; enable it only for specific classes that need lazy loading outside accessors.","When enabling it, extend the plugin classpath to the full dependency set first.","Compile generated and dependent sources before the enhancement task runs."],"tags":["hibernate","bytecode-enhancement","extended-enhancement","classpath","type-resolution"],"backgroundTag":"enhancement-classpath-incomplete","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}