{"record":{"id":"6fa04d3186e024b7","repo":"hibernate/hibernate-orm","slug":"mismatch-between-hibernate-version-used-for-byteco","errorCode":null,"errorMessage":"Mismatch between Hibernate version used for bytecode enhancement (%s) and runtime (%s) for `%s`","messagePattern":"Mismatch between Hibernate version used for bytecode enhancement \\((.+?)\\) and runtime \\((.+?)\\) for `(.+?)`","errorType":"exception","errorClass":"VersionMismatchException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/EnhancerImpl.java","lineNumber":517,"sourceCode":"\t\t\t\t\t\t.to( CodeTemplates.ClearDirtyCollectionNames.class, constants.adviceLocator )\n\t\t\t\t\t\t.wrap( StubMethod.INSTANCE ) )\n\t\t\t\t.defineMethod( REMOVE_DIRTY_FIELDS_NAME, constants.TypeVoid, constants.modifierPUBLIC )\n\t\t\t\t\t\t.withParameter( constants.TypeLazyAttributeLoadingInterceptor )\n\t\t\t\t\t\t.intercept( clearDirtyNames );\n\t}\n\n\tprivate void verifyReEnhancement(\n\t\t\tTypeDescription managedCtClass,\n\t\t\tEnhancementInfo existingInfo,\n\t\t\tByteBuddyEnhancementContext enhancementContext) {\n\t\t// first, make sure versions match\n\t\tfinal String enhancementVersion = existingInfo.version();\n\t\tif ( \"ignore\".equals( enhancementVersion ) ) {\n\t\t\t// for testing\n\t\t\tENHANCEMENT_LOGGER.skippingReEnhancementVersionCheck( managedCtClass.getName() );\n\t\t}\n\t\telse if ( !Version.getVersionString().equals( enhancementVersion ) ) {\n\t\t\tthrow new VersionMismatchException( managedCtClass, enhancementVersion,\n\t\t\t\t\tVersion.getVersionString() );\n\t\t}\n\n\t\tFeatureMismatchException.checkFeatureEnablement(\n\t\t\t\tmanagedCtClass,\n\t\t\t\tDIRTY_CHECK,\n\t\t\t\tenhancementContext.doDirtyCheckingInline(),\n\t\t\t\texistingInfo.includesDirtyChecking()\n\t\t);\n\n\t\tFeatureMismatchException.checkFeatureEnablement(\n\t\t\t\tmanagedCtClass,\n\t\t\t\tASSOCIATION_MANAGEMENT,\n\t\t\t\tenhancementContext.doBiDirectionalAssociationManagement(),\n\t\t\t\texistingInfo.includesAssociationManagement()\n\t\t);\n\t}\n","sourceCodeStart":499,"sourceCodeEnd":535,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/bytecode/enhance/internal/bytebuddy/EnhancerImpl.java#L499-L535","documentation":"When the enhancer encounters a class that already carries Hibernate enhancement instrumentation, verifyReEnhancement() compares the version string stamped into the existing EnhancementInfo against Version.getVersionString() of the running Hibernate. Any difference (except the literal 'ignore', reserved for tests and logged via skippingReEnhancementVersionCheck) throws VersionMismatchException - re-enhancing instrumented bytes from another Hibernate release is unsupported because the internal contract may have changed.","triggerScenarios":"Enhancement running over classes that were already enhanced by a different Hibernate version: stale build outputs after a Hibernate upgrade, a fat jar containing pre-enhanced classes reused as compilation input, or CI caches retaining enhanced classes from the previous dependency version.","commonSituations":"Bumping hibernate-core (e.g. 6.6 -> 7.0) without cleaning build/incremental caches; multi-module builds where an upstream artifact ships enhanced classes and the downstream re-enhances them; IDE incremental compilation keeping old instrumented classes.","solutions":["Clean the build outputs (delete classes/build dirs, invalidate CI cache) so enhancement runs on never-enhanced classes compiled fresh.","Align Hibernate versions across all modules/plugins so the enhancing version matches what produced the classes.","Stop re-enhancing already-enhanced artifacts - consume them as-is or rebuild them from source with the current version.","Test-only: stamp the existing enhancement info version as 'ignore' to bypass the check (it will log skippingReEnhancementVersionCheck); never ship that."],"exampleFix":"# before\n./gradlew compileJava # incremental: keeps classes enhanced by hibernate 6.6, now using 7.0\n# -> VersionMismatchException(enhancementVersion=6.6.x, runtime=7.0.x)\n\n# after\n./gradlew clean compileJava  # enhance from pristine, never-enhanced classes","handlingStrategy":"fallback","validationCode":"// skip re-enhancement of classes already enhanced by another version before calling the enhancer\nstatic boolean needsEnhancement(String className, byte[] bytes, String currentVersion) {\n    return !classNameContainsEnhancementMarker( bytes ) // e.g. Managed interface in constant pool\n            || readsEnhancementVersion( bytes ).equals( currentVersion );\n}","typeGuard":null,"tryCatchPattern":"try { enhanced = enhancer.enhance( className, bytes ); }\ncatch ( VersionMismatchException e ) {\n    // classes were enhanced by a different Hibernate: rebuild from pristine sources\n    cleanOutputsAndRebuild( className ); // then enhance the freshly compiled bytes once\n}","preventionTips":["Always clean builds (or bust incremental/CI caches) after changing the hibernate-core version.","Never feed already-enhanced artifacts back into enhancement; enhance once, from source, per version.","Fail the build with a clear message when a VersionMismatchException is seen in CI rather than retrying it."],"tags":["hibernate","bytecode-enhancement","version-mismatch","build-time","stale-classes"],"backgroundTag":"enhancement-version-mismatch","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}