{"record":{"id":"bc34b786d01ad46f","repo":"quarkusio/quarkus","slug":"bytecode-enhancement-failed-for-class-entityname","errorCode":null,"errorMessage":"Bytecode enhancement failed for class '<entityName>' (it might be due to the Java module system preventing Hibernate ORM from defining an enhanced class in the same package - in this case, the class should be opened and exported to Hibernate ORM)","messagePattern":"Bytecode enhancement failed for class '<entityName>' \\(it might be due to the Java module system preventing Hibernate ORM from defining an enhanced class in the same package - in this case, the class should be opened and exported to Hibernate ORM\\)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"error","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/QuarkusProxyFactory.java","lineNumber":120,"sourceCode":"                persistentClass,\n                interfaces,\n                id,\n                getIdentifierMethod,\n                setIdentifierMethod,\n                componentIdType,\n                session,\n                overridesEquals);\n\n        try {\n            final HibernateProxy proxy = (HibernateProxy) constructor.newInstance();\n            ((ProxyConfiguration) proxy).$$_hibernate_set_interceptor(interceptor);\n            return proxy;\n        } catch (Throwable t) {\n            String logMessage = \"Bytecode enhancement failed for class '\" + entityName\n                    + \"' (it might be due to the Java module system preventing Hibernate ORM from defining an enhanced class in the same package\"\n                    + \" - in this case, the class should be opened and exported to Hibernate ORM)\";\n            LOG.error(logMessage, t);\n            throw new HibernateException(logMessage, t);\n        }\n    }\n}\n","sourceCodeStart":102,"sourceCodeEnd":124,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/QuarkusProxyFactory.java#L102-L124","documentation":"QuarkusProxyFactory.getProxy() loads a bytecode-enhanced entity subclass to create lazy proxies. If loading/defining the proxy fails for any reason, the Throwable is logged and rethrown as a HibernateException with this message. The message calls out the Java module system as a frequent cause: an enhanced class cannot be defined in a non-opened, non-exported package.","triggerScenarios":"Requesting a lazy proxy for an entity whose pre-generated enhanced proxy class fails to load — most commonly because the entity package belongs to a named module that is neither opened nor exported to Hibernate ORM's classloader, or the generated class is missing from the build output.","commonSituations":"Running on the module path (or with strong encapsulation) where entity packages aren't opened to the ORM; native-image or incremental-build artifacts missing generated enhancement classes; classloader isolation preventing resolution of the pre-generated proxy.","solutions":["Open and export the entity's package to Hibernate ORM in module-info.java (opens <package>; exports <package>;) if running with the module system.","Perform a clean rebuild (mvn clean install) to regenerate missing enhanced proxy classes.","Check the logged root cause (the Throwable passed to LOG.error) for the actual LinkageError/ClassNotFound reason.","Avoid running the app on the module path unless module declarations are correct; prefer classpath execution if modules aren't needed.","Verify the entity isn't final and enhancement is enabled so the proxy is generated at build time."],"exampleFix":"// before (module-info.java)\nmodule app { requires org.hibernate.orm.core; }\n\n// after\nmodule app {\n  requires org.hibernate.orm.core;\n  opens com.example.model;\n  exports com.example.model;\n}","handlingStrategy":"try-catch","validationCode":"// Check module openness for the entity package before proxying\nPackage p = MyEntity.class.getPackage();\njava.lang.Module m = MyEntity.class.getModule();\nif (m.isNamed() && !m.isOpen(p.getName(), QuarkusProxyFactory.class.getModule())) {\n    throw new IllegalStateException(\"Module must open \" + p.getName() + \" to Hibernate ORM\");\n}","typeGuard":null,"tryCatchPattern":"try {\n    Entity proxy = session.getReference(Entity.class, id);\n} catch (HibernateException e) {\n    if (e.getMessage() != null && e.getMessage().startsWith(\"Bytecode enhancement failed\")) {\n        log.error(\"Open/export the entity package to Hibernate ORM or rebuild to regenerate proxies\", e);\n    }\n    throw e;\n}","preventionTips":["Add opens/exports for entity packages in module-info.java when on the module path","Run mvn clean after changing enhancement or build-time proxy generation settings","Keep entity classes non-final so build-time proxy generation succeeds","Inspect the logged root cause immediately — it names the exact linkage problem"],"tags":["hibernate-orm","bytecode-enhancement","proxy","java-modules","quarkus"],"backgroundTag":"classloader-class-definition-failed","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}