{"record":{"id":"5efeb42fdf32ad20","repo":"hibernate/hibernate-orm","slug":"s","errorCode":null,"errorMessage":"%s","messagePattern":"%s","errorType":"exception","errorClass":"ClassLoadingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/internal/ClassLoaderAccessImpl.java","lineNumber":66,"sourceCode":"\t\tif ( name == null ) {\n\t\t\tthrow new IllegalArgumentException( \"Name of class to load cannot be null\" );\n\t\t}\n\n\t\tif ( isSafeClass( name ) ) {\n\t\t\treturn classLoaderService.classForName( name );\n\t\t}\n\t\telse {\n\t\t\t// Could not determine that the given class is safe to load with live ClassLoader\n\t\t\tif ( jpaTempClassLoader == null ) {\n\t\t\t\tBOOT_LOGGER.noTempClassLoaderProvidedUsingLiveClassLoader( name );\n\t\t\t\treturn classLoaderService.classForName( name );\n\t\t\t}\n\t\t\telse {\n\t\t\t\ttry {\n\t\t\t\t\treturn jpaTempClassLoader.loadClass( name );\n\t\t\t\t}\n\t\t\t\tcatch (ClassNotFoundException e) {\n\t\t\t\t\tthrow new ClassLoadingException( name );\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t}\n\n\tprivate boolean isSafeClass(String name) {\n\t\t// classes in any of these packages are safe to load through the \"live\" ClassLoader\n\t\treturn name.startsWith( \"java.\" )\n\t\t\t|| name.startsWith( \"javax.\" )\n\t\t\t|| name.startsWith( \"jakarta.\" )\n\t\t\t|| name.startsWith( \"org.hibernate.\" );\n\n\t}\n\n\tpublic ClassLoader getJpaTempClassLoader() {\n\t\treturn jpaTempClassLoader;\n\t}\n","sourceCodeStart":48,"sourceCodeEnd":84,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/internal/ClassLoaderAccessImpl.java#L48-L84","documentation":"When a class name is not in a 'safe' package (java./javax./jakarta./org.hibernate.), Hibernate loads it through the JPA temporary classloader; if that load throws ClassNotFoundException, Hibernate rethrows ClassLoadingException whose message is just the class name (see ClassLoaderAccessImpl.java:66). The named class was simply not found by the classloader that handles entity/converter classes during bootstrap.","triggerScenarios":"jpaTempClassLoader.loadClass(name) throws ClassNotFoundException: the class is absent from the persistence-unit classpath - typo in a mapping's fully-qualified name, missing dependency, or classloader isolation inside an app server hiding entity classes from the temp classloader.","commonSituations":"Misspelled package in <mapping class=...> or persistence.xml <class>; entity module not on the runtime classpath; WAR/EAR deployments where the temp classloader cannot see classes from sibling modules; stale deployments after package renames.","solutions":["Verify the exact fully-qualified name in the message exists on the runtime classpath (Class.forName smoke test)","Fix typos in <mapping class=...>, hbm.xml class names, and persistence.xml <class> entries","Ensure the jar/module containing the class is a dependency of the persistence unit itself, not only of a sibling","In containers, check classloader visibility/delegation policy and redeploy cleanly"],"exampleFix":"<!-- before: typo in the fully-qualified name -->\n<mapping class=\"com.acme.usr.User\"/>\n\n<!-- after -->\n<mapping class=\"com.acme.user.User\"/>","handlingStrategy":"validation","validationCode":"// Fail fast: every mapped class must be visible to the runtime classloader\nfor (String cn : mappedClassNames) {\n    Class.forName(cn, false, Thread.currentThread().getContextClassLoader());\n}","typeGuard":null,"tryCatchPattern":"try {\n    metadata.buildSessionFactory();\n}\ncatch (ClassLoadingException e) {\n    // e.getMessage() is the missing class name: fix the mapping FQN\n    // or make the class visible to the persistence-unit classloader\n}","preventionTips":["Add a startup smoke test that Class.forName's all mapped class names","Keep entity modules on the persistence-unit classpath itself, not only on sibling modules"],"tags":["hibernate","classloading","classpath","entity-mapping"],"backgroundTag":"class-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}