What causes "Embeddable class not found: {}" in hibernate/hibernate-orm?

Copy the exact fully-qualified name (package + class) from the embeddable into the mapping and fix typos.

hibernate/hibernate-orm · error · MappingException

Embeddable class not found: {}

Error message

Embeddable class not found: {}

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/Component.java:374

	public String getComponentClassName() {
		return componentClassName;
	}

	public Class<?> getComponentClass() throws MappingException {
		if ( componentClass == null ) {
			if ( componentClassName == null ) {
				return null;
			}
			else {
				if ( dynamic ) {
					return null;
				}
				try {
					componentClass = classForName( componentClassName, getBootstrapContext() );
				}
				catch (ClassLoadingException e) {
					throw new MappingException( "Embeddable class not found: " + componentClassName, e );
				}
			}
		}
		return componentClass;
	}

	public PersistentClass getOwner() {
		return owner;
	}

	public String getParentProperty() {
		return parentProperty;
	}

	/**
	 * @apiNote This method will be removed in 9.0.
	 */
	@Remove

View on GitHub (pinned to fad1729dce)

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.

Example fix

<!-- before -->
<component name="homeAddress" class="com.acme.Addres"/>

<!-- after -->
<component name="homeAddress" class="com.acme.Address"/>

Defensive patterns

Strategy: validation

Validate before calling

// smoke-test every hbm-declared component class before building the factory
static void assertLoadable(String fqn) throws ClassNotFoundException {
    Class.forName(fqn, false, Thread.currentThread().getContextClassLoader());
}

Try / catch

try {
    sessionFactory = configuration.buildSessionFactory();
} catch (MappingException e) {
    if (e.getCause() instanceof ClassLoadingException cle) {
        // fix the class name in the mapping or add the jar to the classpath
        throw new IllegalStateException("Unloadable embeddable: " + cle.getMessage(), e);
    }
    throw e;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of hibernate/hibernate-orm@fad1729dce (2026-08-22). Data as JSON: /api/errors/18020980ed716195. Report an issue: GitHub.