quarkusio/quarkus · error · HibernateException

Bytecode enhancement failed for class '<entityName>' (it mig

Error message

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)

What it means

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.

Source

Thrown at extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/QuarkusProxyFactory.java:120

                persistentClass,
                interfaces,
                id,
                getIdentifierMethod,
                setIdentifierMethod,
                componentIdType,
                session,
                overridesEquals);

        try {
            final HibernateProxy proxy = (HibernateProxy) constructor.newInstance();
            ((ProxyConfiguration) proxy).$$_hibernate_set_interceptor(interceptor);
            return proxy;
        } catch (Throwable t) {
            String logMessage = "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)";
            LOG.error(logMessage, t);
            throw new HibernateException(logMessage, t);
        }
    }
}

View on GitHub (pinned to e1c734241f)

Solutions

1. Open and export the entity's package to Hibernate ORM in module-info.java (opens <package>; exports <package>;) if running with the module system.
2. Perform a clean rebuild (mvn clean install) to regenerate missing enhanced proxy classes.
3. Check the logged root cause (the Throwable passed to LOG.error) for the actual LinkageError/ClassNotFound reason.
4. Avoid running the app on the module path unless module declarations are correct; prefer classpath execution if modules aren't needed.
5. Verify the entity isn't final and enhancement is enabled so the proxy is generated at build time.

Example fix

// before (module-info.java)
module app { requires org.hibernate.orm.core; }

// after
module app {
  requires org.hibernate.orm.core;
  opens com.example.model;
  exports com.example.model;
}

// Check module openness for the entity package before proxying
Package p = MyEntity.class.getPackage();
java.lang.Module m = MyEntity.class.getModule();
if (m.isNamed() && !m.isOpen(p.getName(), QuarkusProxyFactory.class.getModule())) {
    throw new IllegalStateException("Module must open " + p.getName() + " to Hibernate ORM");
}

try {
    Entity proxy = session.getReference(Entity.class, id);
} catch (HibernateException e) {
    if (e.getMessage() != null && e.getMessage().startsWith("Bytecode enhancement failed")) {
        log.error("Open/export the entity package to Hibernate ORM or rebuild to regenerate proxies", e);
    }
    throw e;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Could not lookup a pre-generated proxy class definition for
• Invalid proxy passed to recorder. ${rp} was created in a run
• You cannot invoke ${method.getName()}() directly on an objec
• Failed to read class bytes for '${className}', class not pre
• Failed to read Model class

AI-assisted analysis of quarkusio/quarkus@e1c734241f (2026-09-05). Data as JSON: /api/errors/bc34b786d01ad46f. Report an issue: GitHub.