{"record":{"id":"5effa4e7678ff1eb","repo":"hibernate/hibernate-orm","slug":"unable-to-perform-extended-enhancement-no-unique","errorCode":null,"errorMessage":"Unable to perform extended enhancement - No unique field [%s] defined by [%s]","messagePattern":"Unable to perform extended enhancement - No unique field \\[(.+?)\\] defined by \\[(.+?)\\]","errorType":"exception","errorClass":"EnhancementException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/FieldAccessEnhancer.java","lineNumber":131,"sourceCode":"\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}\n\n\tprivate static @Nonnull FieldList<?> findFields(TypeDescription declaredOwnedType, String name, String desc) {\n\t\tTypeDefinition ownerType = declaredOwnedType;\n\t\tfinal var fieldFilter = named( name ).and( hasDescriptor( desc ) );\n\t\tFieldList<?> fields = ownerType.getDeclaredFields().filter( fieldFilter );\n\t\t// Look in the superclasses if necessary\n\t\twhile ( fields.isEmpty() && ownerType.getSuperClass() != null ) {\n\t\t\townerType = ownerType.getSuperClass();\n\t\t\tfields = ownerType.getDeclaredFields().filter( fieldFilter );\n\t\t}\n\t\treturn fields;","sourceCodeStart":113,"sourceCodeEnd":149,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/FieldAccessEnhancer.java#L113-L149","documentation":"During extended enhancement, after resolving the owner type of a field instruction, FieldAccessEnhancer.findField() looks for exactly one declared field matching both name and descriptor (named(name).and(hasDescriptor(desc))) walking the hierarchy. If the filtered list does not contain exactly one element - typically zero because the owner type resolved from the classpath is a different version whose field has a different descriptor/signature - it throws EnhancementException('No unique field [<name>] defined by [<owner>]').","triggerScenarios":"enableExtendedEnhancement(true) while the classpath holds a different version of the owner type than the one the class was compiled against: a field's type changed between versions (so the descriptor differs), the field was renamed/removed, or duplicate classes with conflicting field signatures are both visible.","commonSituations":"Conflicting dependency versions on the enhancement classpath (the classic 'two versions of the same library' problem surfacing as a descriptor mismatch); upgrading one library whose API changed a field type while the enhancer resolves the other; shaded jars bundling stale copies of a class.","solutions":["Align the enhancement classpath with the exact versions the entity classes were compiled against (dependencyManagement/lockfile) so the resolved field descriptor matches.","Check for duplicate classes (same FQCN) across jars on the enhancement classpath and evict the stale copy.","Disable extended enhancement if it is not strictly required - the error only occurs on that path.","Use the message's owner type + field name to identify which artifact must be version-aligned."],"exampleFix":"# before\n# entity compiled against lib-2.0 (field: Optional<X> x), enhancement classpath has lib-1.9 (field: X x)\n# -> findFields matches 0 -> 'No unique field [x] defined by [com.lib.Owner]'\n\n# after\n# gradle\nconfigurations.enhanceClasspath { resolutionStrategy { force 'com.lib:lib:2.0' } } # or align via platform/BOM","handlingStrategy":"fallback","validationCode":"// pre-flight: the enhancement classpath must contain the same owner-type versions the classes were compiled against\nstatic boolean fieldDescriptorsMatch(ClassLoader cl, String owner, String field, String expectedDesc) throws Exception {\n    Class<?> c = Class.forName( owner, false, cl );\n    for ( var f : c.getDeclaredFields() ) {\n        if ( f.getName().equals( field ) ) { return descriptorOf( f.getType() ).equals( expectedDesc ); }\n    }\n    return false;\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Lock dependency versions (BOM/platform) so compile and enhancement classpaths cannot diverge.","Detect duplicate classes across jars on the enhancement classpath and evict stale copies.","Keep extended enhancement off unless required - findField() uniqueness checks run only on that path."],"tags":["hibernate","bytecode-enhancement","extended-enhancement","classpath","version-conflict"],"backgroundTag":"enhancement-classpath-incomplete","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}