hibernate/hibernate-orm · error · IllegalArgumentException

Name of class to load cannot be null

Error message

Name of class to load cannot be null

What it means

ClassLoaderAccessImpl.classForName(name) is the gate through which all class loading during metadata processing goes, and it rejects a null name immediately with IllegalArgumentException 'Name of class to load cannot be null'. A null reaching it means some mapping or caller tried to resolve a class without actually having a class name.

Source

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

	}

	public ClassLoaderAccessImpl(ClassLoader tempClassLoader, ServiceRegistry serviceRegistry) {
		this( tempClassLoader, serviceRegistry.getService( ClassLoaderService.class ) );
	}

	public ClassLoaderAccessImpl(ClassLoaderService classLoaderService) {
		this( null, classLoaderService );
	}

	public void injectTempClassLoader(ClassLoader jpaTempClassLoader) {
		this.jpaTempClassLoader = jpaTempClassLoader;
	}

	@Override
	@SuppressWarnings("unchecked")
	public Class<?> classForName(String name) {
		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 );
				}

View on GitHub (pinned to fad1729dce)

Solutions

1. Inspect the mapping identified in the stack trace and give the entity/component a real fully-qualified class name
2. Null-check the name at the call site and fail with a descriptive mapping error instead of calling classForName(null)
3. If dynamic map-backed entities are intended, configure them so no class name is resolved at all

Example fix

// before
classLoaderAccess.classForName(persistentClass.getClassName()); // may be null

// after
String cn = Objects.requireNonNull(
        persistentClass.getClassName(),
        "entity has no class name: " + persistentClass.getEntityName());
classLoaderAccess.classForName(cn);

if (name == null || name.isBlank()) {
    throw new IllegalArgumentException(
            "Mapping must declare a class name, got: " + mappingSource);
}
return classLoaderAccess.classForName(name);

static boolean hasClassName(String name) {
    return name != null && !name.isBlank();
}

When it happens

Trigger: Passing null to ClassLoaderAccess.classForName from programmatic metadata or an integration; a mapping whose class-name resolution returned null and was forwarded unchecked (e.g. a hand-edited hbm.xml <class> without a usable name, or a reflection-based mapping where the lookup missed).

Common situations: Hand-edited XML mappings with missing or empty name attributes; generated mapping templates where a placeholder did not fill; custom Integrators/MetadataSourceProcessors forwarding unresolved names.

Related errors

• The specified class cannot be null
• Embeddable class not found: {}
• entity class not found: " + className
• proxy class not found: " + proxyInterfaceName
• The INSERT statement for table [%s] contains no column, and

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