hibernate/hibernate-orm · error · ClassLoadingException

%s

Error message

%s

What it means

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.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/ClassLoaderAccessImpl.java:66

		if ( name == null ) {
			throw new IllegalArgumentException( "Name of class to load cannot be null" );
		}

		if ( isSafeClass( name ) ) {
			return classLoaderService.classForName( name );
		}
		else {
			// Could not determine that the given class is safe to load with live ClassLoader
			if ( jpaTempClassLoader == null ) {
				BOOT_LOGGER.noTempClassLoaderProvidedUsingLiveClassLoader( name );
				return classLoaderService.classForName( name );
			}
			else {
				try {
					return jpaTempClassLoader.loadClass( name );
				}
				catch (ClassNotFoundException e) {
					throw new ClassLoadingException( name );
				}
			}
		}
	}

	private boolean isSafeClass(String name) {
		// classes in any of these packages are safe to load through the "live" ClassLoader
		return name.startsWith( "java." )
			|| name.startsWith( "javax." )
			|| name.startsWith( "jakarta." )
			|| name.startsWith( "org.hibernate." );

	}

	public ClassLoader getJpaTempClassLoader() {
		return jpaTempClassLoader;
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Verify the exact fully-qualified name in the message exists on the runtime classpath (Class.forName smoke test)
2. Fix typos in <mapping class=...>, hbm.xml class names, and persistence.xml <class> entries
3. Ensure the jar/module containing the class is a dependency of the persistence unit itself, not only of a sibling
4. In containers, check classloader visibility/delegation policy and redeploy cleanly

Example fix

<!-- before: typo in the fully-qualified name -->
<mapping class="com.acme.usr.User"/>

<!-- after -->
<mapping class="com.acme.user.User"/>

// Fail fast: every mapped class must be visible to the runtime classloader
for (String cn : mappedClassNames) {
    Class.forName(cn, false, Thread.currentThread().getContextClassLoader());
}

try {
    metadata.buildSessionFactory();
}
catch (ClassLoadingException e) {
    // e.getMessage() is the missing class name: fix the mapping FQN
    // or make the class visible to the persistence-unit classloader
}

When it happens

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

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

Related errors

• Unable to load class [" + className + "]
• Could not resolve named type: {}
• Embeddable class not found: {}
• Entity '<entityName>' is not audited
• Entity '<entityName>' is not audited

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