{"record":{"id":"544cf575008818d6","repo":"quarkusio/quarkus","slug":"could-not-lookup-a-pre-generated-proxy-class-defin","errorCode":null,"errorMessage":"Could not lookup a pre-generated proxy class definition for entity '%s' (class='%s'): %s","messagePattern":"Could not lookup a pre-generated proxy class definition for entity '(.+?)' \\(class='(.+?)'\\): (.+?)","errorType":"exception","errorClass":"HibernateException","httpStatus":null,"severity":"warning","filePath":"extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/QuarkusProxyFactory.java","lineNumber":72,"sourceCode":"        this.interfaces = toArray(interfaces);\n        this.getIdentifierMethod = getIdentifierMethod;\n        this.setIdentifierMethod = setIdentifierMethod;\n        this.componentIdType = componentIdType;\n        ProxyDefinitions.ProxyClassDetailsHolder detailsHolder = proxyClassDefinitions.getProxyForClass(persistentClass);\n        if (detailsHolder == null) {\n            String reason = null;\n            // Some Envers entity classes are final, e.g. org.hibernate.envers.DefaultRevisionEntity\n            // There's nothing users can do about it, so let's not fail in those cases.\n            if (persistentClass.getName().startsWith(\"org.hibernate.\")) {\n                reason = \"this is a limitation of this particular Hibernate class.\";\n            }\n            // See also ProxyBuildingHelper#isProxiable\n            else if (Modifier.isFinal(persistentClass.getModifiers())) {\n                reason = \"this class is final. Your application might perform better if this class was non-final.\";\n            }\n            if (reason != null) {\n                // This is caught and logged as a warning by Hibernate ORM.\n                throw new HibernateException(String.format(Locale.ROOT,\n                        \"Could not lookup a pre-generated proxy class definition for entity '%s' (class='%s'): %s\", entityName,\n                        persistentClass.getCanonicalName(), reason));\n            } else {\n                // This will fail bootstrap.\n                throw new IllegalStateException(String.format(Locale.ROOT,\n                        \"Could not lookup a pre-generated proxy class definition for entity '%s' (class='%s').\" +\n                                \"This should not happen, please open an issue at https://github.com/quarkusio/quarkus/issues\",\n                        entityName, persistentClass.getCanonicalName()));\n            }\n        }\n        this.overridesEquals = detailsHolder.isOverridesEquals();\n        this.constructor = detailsHolder.getConstructor();\n\n    }\n\n    private static Class<?>[] toArray(Set<Class<?>> interfaces) {\n        if (interfaces == null) {\n            return ArrayHelper.EMPTY_CLASS_ARRAY;","sourceCodeStart":54,"sourceCodeEnd":90,"githubUrl":"https://github.com/quarkusio/quarkus/blob/e1c734241f34c7919086ceb4c9262b4a58f6de44/extensions/hibernate-orm/runtime/src/main/java/io/quarkus/hibernate/orm/runtime/customized/QuarkusProxyFactory.java#L54-L90","documentation":"Quarkus generates lazy-load proxies for entities at build time; QuarkusProxyFactory.postInstantiate() looks up the pre-generated proxy definition when a persistence unit starts. If the entity's class cannot be proxied (it is final, or has a final/overridden-incompatible method), a HibernateException is thrown with a reason explaining why. This variant is intended to be caught and logged as a warning by Hibernate ORM.","triggerScenarios":"Bootstrapping a persistence unit containing an entity class that is final, or whose key methods are final, so no pre-generated proxy definition exists; postInstantiate then builds the reason string ('this class is final...') and throws.","commonSituations":"Declaring an @Entity class or its getId() method as final; upgrading Quarkus and adding an entity that violates proxying rules; classes enhanced/obfuscated in ways preventing proxy generation.","solutions":["Make the entity class non-final and keep its no-arg constructor and property getters non-final so Hibernate can generate lazy proxies.","If finality is intentional and lazy loading is not needed, disable proxying for the entity (lazy=\"no-proxy\"/@Lazy(false)-style options or lazy=false mappings).","Check build logs for why the proxy class wasn't pre-generated for this entity and fix the modeling issue.","Ensure the entity type is compiled with a public/protected no-arg constructor as required by JPA."],"exampleFix":"// before\npublic final class Order { ... }\n\n// after\npublic class Order { ... }","handlingStrategy":"validation","validationCode":"// Validate entity proxyability before bootstrapping\nstatic <T> String checkProxiable(Class<T> entity) {\n    if (java.lang.reflect.Modifier.isFinal(entity.getModifiers())) {\n        return \"entity class is final\";\n    }\n    if (java.lang.reflect.Modifier.isFinal(entity.getConstructors()[0].getModifiers())) {\n        return \"constructor is final\";\n    }\n    return null;\n}","typeGuard":"static boolean isProxyable(Class<?> c) {\n    return !java.lang.reflect.Modifier.isFinal(c.getModifiers())\n        && !c.isRecord()\n        && java.lang.reflect.Modifier.isPublic(c.getModifiers());\n}","tryCatchPattern":"try {\n    emf = Persistence.createEntityManagerFactory(\"pu\");\n} catch (HibernateException e) {\n    if (e.getMessage() != null && e.getMessage().contains(\"pre-generated proxy class definition\")) {\n        log.warn(\"Entity not proxiable: \" + e.getMessage() + \" — make it non-final or disable lazy proxying\");\n    }\n    throw e;\n}","preventionTips":["Never mark @Entity classes or their accessors final","Keep a non-final public/protected no-arg constructor on every entity","Review new entities against proxying rules (non-final class, non-final getId) in code review"],"tags":["hibernate-orm","proxy","lazy-loading","entity","quarkus"],"backgroundTag":"entity-not-proxiable","analyzedSha":"e1c734241f34c7919086ceb4c9262b4a58f6de44","analyzedAt":"2026-09-05T17:01:29.979Z","contentChangedAt":"2026-09-05T17:01:29.979Z","schemaVersion":2},"datasetVersion":"2026-09-12T22:17:10.623Z"}