{"record":{"id":"281cb04c3e87c4db","repo":"hibernate/hibernate-orm","slug":"entity-class-not-found-classname","errorCode":null,"errorMessage":"entity class not found: \" + className","messagePattern":"entity class not found: \" \\+ className","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java","lineNumber":176,"sourceCode":"\t\tthis.proxyInterface = null;\n\t}\n\n\tprivate Class<?> getClassForName(String className) {\n\t\treturn classForName( className, metadataBuildingContext.getBootstrapContext() );\n\t}\n\n\tpublic Class<?> getMappedClass() throws MappingException {\n\t\tif ( className == null ) {\n\t\t\treturn null;\n\t\t}\n\t\ttry {\n\t\t\tif ( mappedClass == null ) {\n\t\t\t\tmappedClass = getClassForName( className );\n\t\t\t}\n\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","sourceCodeStart":158,"sourceCodeEnd":194,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java#L158-L194","documentation":"Thrown while Hibernate resolves the Java class behind a mapped entity. PersistentClass.getMappedClass() lazily loads the class name recorded in the mapping (hbm.xml, annotations, or programmatic binding); if the class is not visible to Hibernate's classloader, the ClassLoadingException is wrapped in this MappingException. It almost always means the mapping names a class that is not on the runtime classpath.","triggerScenarios":"Building a SessionFactory from an hbm.xml whose class name attribute has a typo or wrong package; deploying with entity classes in a jar loaded by a different ClassLoader than hibernate-core (app-server deployment isolation, shaded jars); mappings built on one machine and deserialized in an environment where the class is absent.","commonSituations":"Entity jar missing from the WAR/EAR artifact; package rename refactoring that missed mapping files; test classpath missing main sources; ProGuard/R8 stripping classes referenced only from XML; multi-module builds where the mapping module is ahead of the entity module.","solutions":["Verify the class exists in the deployed artifact (for example: jar tf app.jar) and fix the packaging","Fix the class name in the hbm.xml class element or the annotated entity (typos, wrong package)","Ensure entity classes and hibernate-core are loaded by the same ClassLoader (put entity jars in the same deployment)","For programmatic mappings, pass the Class object instead of a String name so mistakes surface at compile time"],"exampleFix":"// before (User.hbm.xml)\n<class name=\"com.acme.Userr\" table=\"users\">\n\n// after\n<class name=\"com.acme.User\" table=\"users\">","handlingStrategy":"validation","validationCode":"// before building the SessionFactory, verify every mapped class is loadable here\nfor (PersistentClass pc : metadata.getEntityBindings()) {\n    String cn = pc.getClassName();\n    if (cn == null) continue;\n    try {\n        Class.forName(cn, false, Thread.currentThread().getContextClassLoader());\n    }\n    catch (ClassNotFoundException e) {\n        throw new IllegalStateException(cn, e); // mapped class not on classpath\n    }\n}","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = metadata.buildSessionFactory();\n}\ncatch (org.hibernate.MappingException e) {\n    if (e.getCause() instanceof org.hibernate.boot.registry.classloading.spi.ClassLoadingException) {\n        // classpath/deployment problem: fix packaging, do not retry\n    }\n    throw e;\n}","preventionTips":["Prefer annotation-based mappings so class references are compile-checked","Add a CI smoke test that builds the SessionFactory against the exact packaged artifact","Keep entity classes and hibernate-core in the same classloader scope"],"tags":["hibernate","orm","classloading","mapping","session-factory"],"backgroundTag":"class-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}