{"record":{"id":"5be09657e268f5da","repo":"hibernate/hibernate-orm","slug":"failed-to-enhance-class-classname","errorCode":null,"errorMessage":"Failed to enhance class {className}","messagePattern":"Failed to enhance class (.+?)","errorType":"exception","errorClass":"EnhancementException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/EnhancerImpl.java","lineNumber":163,"sourceCode":"\t@Override\n\tpublic byte[] enhance(String className, byte[] originalBytes) throws EnhancementException {\n\t\t//Classpool#describe does not accept '/' in the description name as it expects a class name. See HHH-12545\n\t\tfinal String safeClassName = className.replace( '/', '.' );\n\t\ttypePool.registerClassNameAndBytes( safeClassName, originalBytes );\n\t\ttry {\n\t\t\tfinal var typeDescription = typePool.describe( safeClassName ).resolve();\n\t\t\treturn byteBuddyState.rewrite( typePool, safeClassName, byteBuddy ->\n\t\t\t\t\tdoEnhance( () -> byteBuddy.ignore( constants.defaultFinalizer() )\n\t\t\t\t\t\t\t\t\t.redefine( typeDescription, typePool.asClassFileLocator() )\n\t\t\t\t\t\t\t\t\t.annotateType( infoAnnotationList ),\n\t\t\t\t\t\t\ttypeDescription\n\t\t\t\t\t) );\n\t\t}\n\t\tcatch (EnhancementException e) {\n\t\t\tthrow e;\n\t\t}\n\t\tcatch (RuntimeException e) {\n\t\t\tthrow new EnhancementException( \"Failed to enhance class \" + className, e );\n\t\t}\n\t\tfinally {\n\t\t\ttypePool.deregisterClassNameAndBytes( safeClassName );\n\t\t}\n\t}\n\n\t@Override\n\tpublic void discoverTypes(String className, byte[] originalBytes) {\n\t\tif ( originalBytes != null ) {\n\t\t\ttypePool.registerClassNameAndBytes( className, originalBytes );\n\t\t}\n\t\ttry {\n\t\t\tfinal var typeDescription = typePool.describe( className ).resolve();\n\t\t\tenhancementContext.registerDiscoveredType( typeDescription, Type.PersistenceType.ENTITY );\n\t\t\tenhancementContext.discoverCompositeTypes( typeDescription, typePool );\n\t\t}\n\t\tcatch (RuntimeException e) {\n\t\t\tthrow new EnhancementException( \"Failed to discover types for class \" + className, e );","sourceCodeStart":145,"sourceCodeEnd":181,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/EnhancerImpl.java#L145-L181","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\nbyte[] enhanced = enhancer.enhance( \"com.acme.Order\", originalBytes ); // throws EnhancementException\n\n// after\ntry { enhanced = enhancer.enhance( \"com.acme.Order\", originalBytes ); }\ncatch ( EnhancementException e ) { log.error( \"cause:\", e.getCause() ); throw e; }\n// and fix the root cause, e.g. bump hibernate-core for the newer class-file version","handlingStrategy":"try-catch","validationCode":"// fail fast when the entity class file is newer than the enhancer's Byte Buddy supports\nstatic int classFileMajor(byte[] bytes) { return ( ( bytes[6] & 0xFF ) << 8 ) | ( bytes[7] & 0xFF ); }\nstatic boolean supportedByThisEnhancer(byte[] bytes) { return classFileMajor( bytes ) <= 65; } // check your hibernate-core release","typeGuard":null,"tryCatchPattern":"try {\n    enhanced = enhancer.enhance( className, originalBytes );\n}\ncatch ( EnhancementException e ) {\n    if ( ( \"Failed to enhance class \" + className ).equals( e.getMessage() ) ) {\n        Throwable root = e.getCause(); // real reason: unsupported class file version, resolution error, visitor bug\n        diagnostics.add( className + \" -> \" + root );\n    }\n    throw e;\n}","preventionTips":["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."],"tags":["hibernate","bytecode-enhancement","byte-buddy","build-time","java-version"],"backgroundTag":"bytecode-enhancement-failure","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}