hibernate/hibernate-orm · error · MappingException

entity class not found: " + className

Error message

entity class not found: " + className

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/mapping/PersistentClass.java:176

		this.proxyInterface = null;
	}

	private Class<?> getClassForName(String className) {
		return classForName( className, metadataBuildingContext.getBootstrapContext() );
	}

	public Class<?> getMappedClass() throws MappingException {
		if ( className == null ) {
			return null;
		}
		try {
			if ( mappedClass == null ) {
				mappedClass = getClassForName( className );
			}
			return mappedClass;
		}
		catch (ClassLoadingException e) {
			throw new MappingException( "entity class not found: " + className, e );
		}
	}

	public Class<?> getProxyInterface() {
		if ( proxyInterfaceName == null ) {
			return null;
		}
		try {
			if ( proxyInterface == null ) {
				proxyInterface = getClassForName( proxyInterfaceName );
			}
			return proxyInterface;
		}
		catch (ClassLoadingException e) {
			throw new MappingException( "proxy class not found: " + proxyInterfaceName, e );
		}
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Verify the class exists in the deployed artifact (for example: jar tf app.jar) and fix the packaging
2. Fix the class name in the hbm.xml class element or the annotated entity (typos, wrong package)
3. Ensure entity classes and hibernate-core are loaded by the same ClassLoader (put entity jars in the same deployment)
4. For programmatic mappings, pass the Class object instead of a String name so mistakes surface at compile time

Example fix

// before (User.hbm.xml)
<class name="com.acme.Userr" table="users">

// after
<class name="com.acme.User" table="users">

// before building the SessionFactory, verify every mapped class is loadable here
for (PersistentClass pc : metadata.getEntityBindings()) {
    String cn = pc.getClassName();
    if (cn == null) continue;
    try {
        Class.forName(cn, false, Thread.currentThread().getContextClassLoader());
    }
    catch (ClassNotFoundException e) {
        throw new IllegalStateException(cn, e); // mapped class not on classpath
    }
}

try {
    sessionFactory = metadata.buildSessionFactory();
}
catch (org.hibernate.MappingException e) {
    if (e.getCause() instanceof org.hibernate.boot.registry.classloading.spi.ClassLoadingException) {
        // classpath/deployment problem: fix packaging, do not retry
    }
    throw e;
}

When it happens

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

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

Related errors

• Embeddable class not found: {}
• proxy class not found: " + proxyInterfaceName
• Name of class to load cannot be null
• Identifier property '" + getPath( holder, data ) + "' cannot
• Attribute '%s' of entity '%s' is mapped by association '%s'

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