{"record":{"id":"18020980ed716195","repo":"hibernate/hibernate-orm","slug":"embeddable-class-not-found","errorCode":null,"errorMessage":"Embeddable class not found: {}","messagePattern":"Embeddable class not found: (.+?)","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/mapping/Component.java","lineNumber":374,"sourceCode":"\n\tpublic String getComponentClassName() {\n\t\treturn componentClassName;\n\t}\n\n\tpublic Class<?> getComponentClass() throws MappingException {\n\t\tif ( componentClass == null ) {\n\t\t\tif ( componentClassName == null ) {\n\t\t\t\treturn null;\n\t\t\t}\n\t\t\telse {\n\t\t\t\tif ( dynamic ) {\n\t\t\t\t\treturn null;\n\t\t\t\t}\n\t\t\t\ttry {\n\t\t\t\t\tcomponentClass = classForName( componentClassName, getBootstrapContext() );\n\t\t\t\t}\n\t\t\t\tcatch (ClassLoadingException e) {\n\t\t\t\t\tthrow new MappingException( \"Embeddable class not found: \" + componentClassName, e );\n\t\t\t\t}\n\t\t\t}\n\t\t}\n\t\treturn componentClass;\n\t}\n\n\tpublic PersistentClass getOwner() {\n\t\treturn owner;\n\t}\n\n\tpublic String getParentProperty() {\n\t\treturn parentProperty;\n\t}\n\n\t/**\n\t * @apiNote This method will be removed in 9.0.\n\t */\n\t@Remove","sourceCodeStart":356,"sourceCodeEnd":392,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/mapping/Component.java#L356-L392","documentation":"Component#getComponentClass() loads the embeddable class by its configured name and converts a ClassLoadingException into this MappingException. It means the class named for a component/embeddable mapping cannot be loaded by Hibernate's class loader. Only string-based mappings (hbm.xml, programmatic) hit it; pure annotation mappings reference the class itself.","triggerScenarios":"An hbm.xml <component class=\"...\"> or <composite-id class=\"...\"> with a misspelled or outdated fully-qualified name; the embeddable lives in a jar not on the runtime classpath of the persistence unit; the class was renamed or moved during refactoring while the XML mapping was not updated; modular deployments (JPMS, app server tiers) hiding the domain package.","commonSituations":"Refactorings that move embeddables into another package; multi-module projects where the mapping module is deployed without the domain jar; stale build artifacts after a rename; copy-paste of hbm files between projects.","solutions":["Copy the exact fully-qualified name (package + class) from the embeddable into the mapping and fix typos.","Verify the artifact containing the embeddable is on the runtime classpath (dependencies, EAR/lib, module exports).","Rebuild and redeploy to eliminate stale classes when the name already looks correct.","Prefer JPA annotations or the programmatic API that reference the Class object directly, removing name-based lookups."],"exampleFix":"<!-- before -->\n<component name=\"homeAddress\" class=\"com.acme.Addres\"/>\n\n<!-- after -->\n<component name=\"homeAddress\" class=\"com.acme.Address\"/>","handlingStrategy":"validation","validationCode":"// smoke-test every hbm-declared component class before building the factory\nstatic void assertLoadable(String fqn) throws ClassNotFoundException {\n    Class.forName(fqn, false, Thread.currentThread().getContextClassLoader());\n}","typeGuard":null,"tryCatchPattern":"try {\n    sessionFactory = configuration.buildSessionFactory();\n} catch (MappingException e) {\n    if (e.getCause() instanceof ClassLoadingException cle) {\n        // fix the class name in the mapping or add the jar to the classpath\n        throw new IllegalStateException(\"Unloadable embeddable: \" + cle.getMessage(), e);\n    }\n    throw e;\n}","preventionTips":["Run a mapping smoke test that builds the SessionFactory at startup in dev and CI.","Reference embeddables by Class via annotations or the programmatic API instead of string names.","Keep hbm.xml files in the same module as the classes they name so refactorings update both."],"tags":["hibernate","orm","mapping","embeddable","classpath","classloading","hbm"],"backgroundTag":"class-not-found","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}