{"record":{"id":"b76f2ce17e86452c","repo":"hibernate/hibernate-orm","slug":"proxy-class-not-found-proxyinterfacename","errorCode":null,"errorMessage":"proxy class not found: \" + proxyInterfaceName","messagePattern":"proxy class not found: \" \\+ proxyInterfaceName","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java","lineNumber":191,"sourceCode":"\t\t\treturn mappedClass;\n\t\t}\n\t\tcatch (ClassLoadingException e) {\n\t\t\tthrow new MappingException( \"entity class not found: \" + className, e );\n\t\t}\n\t}\n\n\tpublic Class<?> getProxyInterface() {\n\t\tif ( proxyInterfaceName == null ) {\n\t\t\treturn null;\n\t\t}\n\t\ttry {\n\t\t\tif ( proxyInterface == null ) {\n\t\t\t\tproxyInterface = getClassForName( proxyInterfaceName );\n\t\t\t}\n\t\t\treturn proxyInterface;\n\t\t}\n\t\tcatch (ClassLoadingException e) {\n\t\t\tthrow new MappingException( \"proxy class not found: \" + proxyInterfaceName, e );\n\t\t}\n\t}\n\n\tpublic boolean useDynamicInsert() {\n\t\treturn dynamicInsert;\n\t}\n\n\tabstract int nextSubclassId();\n\n\tpublic abstract int getSubclassId();\n\n\tpublic boolean useDynamicUpdate() {\n\t\treturn dynamicUpdate;\n\t}\n\n\tpublic void setDynamicInsert(boolean dynamicInsert) {\n\t\tthis.dynamicInsert = dynamicInsert;\n\t}","sourceCodeStart":173,"sourceCodeEnd":209,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java#L173-L209","documentation":"Thrown when Hibernate cannot load the interface used to generate proxies for an entity. PersistentClass.getProxyInterface() resolves the proxyInterfaceName recorded from @Proxy(proxyInterface=...) or the proxy element in hbm.xml; a ClassLoadingException is wrapped in this MappingException. The mapping names a proxy interface that is not on the classpath (or has been renamed).","triggerScenarios":"An entity annotated @Proxy(proxyInterface = SomeApi.class) where SomeApi lives in a jar absent from the runtime classpath; an hbm proxy interface attribute holding a stale name after an interface rename; the referenced type exists but the mapping points at the implementing class rather than an interface.","commonSituations":"Splitting API and model into separate artifacts and forgetting the API jar on the server; refactors that renamed proxy interfaces without regenerating XML; copy-pasting proxy settings between entities.","solutions":["Fix the interface name in @Proxy(proxyInterface=...) or the hbm proxy element","Ship the artifact that contains the proxy interface with the deployment","Remove the @Proxy annotation if default proxying of the entity class itself is acceptable"],"exampleFix":"// before\n@Entity\n@Proxy(proxyInterface = OldUserApi.class)\npublic class User implements UserApi { ... }\n\n// after\n@Entity\n@Proxy(proxyInterface = UserApi.class)\npublic class User implements UserApi { ... }","handlingStrategy":"validation","validationCode":"for (PersistentClass pc : metadata.getEntityBindings()) {\n    String proxy = pc.getProxyInterfaceName();\n    if (proxy == null) continue;\n    Class<?> iface = Class.forName(proxy, false, cl);\n    if (!iface.isInterface()) {\n        throw new IllegalArgumentException(proxy); // proxy target must be an interface\n    }\n}","typeGuard":"static boolean isLoadableInterface(String name, ClassLoader cl) {\n    try {\n        return Class.forName(name, false, cl).isInterface();\n    }\n    catch (ClassNotFoundException e) {\n        return false;\n    }\n}","tryCatchPattern":null,"preventionTips":["Reference proxy interfaces by class literal (@Proxy(proxyInterface = UserApi.class)), never by string","Make proxy interfaces part of the same artifact as the entity or a guaranteed dependency","Drop @Proxy unless you actually need interface-based lazy proxies"],"tags":["hibernate","orm","proxy","classloading","mapping"],"backgroundTag":"class-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}