hibernate/hibernate-orm · error · IllegalArgumentException

Can't load class: {}

Error message

Can't load class: {}

What it means

Thrown by EntityManagerFactoryBuilderImpl.loadSettingInstance() as an IllegalArgumentException when a configuration setting that must resolve to a class (e.g. an Interceptor, SessionFactoryObserver, or similar strategy) is given as a String class name and Class.forName() cannot find it. It only occurs on the code path where the standardServiceRegistry is not yet available, so the plain system ClassLoader is used. The missing class name is included in the message.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/jpa/boot/internal/EntityManagerFactoryBuilderImpl.java:1720

		final Class<? extends T> instanceClass;
		if ( clazz.isInstance( settingValue ) ) {
			return clazz.cast( settingValue );
		}
		else if ( settingValue instanceof Class ) {
			instanceClass = (Class<? extends T>) settingValue;
		}
		else if ( settingValue instanceof String className ) {
			if ( standardServiceRegistry != null ) {
				instanceClass =
						standardServiceRegistry.requireService( ClassLoaderService.class )
								.classForName( className );
			}
			else {
				try {
					instanceClass = (Class<? extends T>) Class.forName( className );
				}
				catch (ClassNotFoundException e) {
					throw new IllegalArgumentException( "Can't load class: " + className, e );
				}
			}
		}
		else {
			throw new IllegalArgumentException( "The provided " + settingName
					+ " setting value [" + settingValue + "] is not supported" );
		}

		if ( instanceClass != null ) {
			try {
				return instanceClass.newInstance();
			}
			catch (InstantiationException | IllegalAccessException e) {
				throw new IllegalArgumentException(
						"The " + clazz.getSimpleName() +" class [" + instanceClass + "] could not be instantiated",
						e
				);
			}

View on GitHub (pinned to fad1729dce)

Solutions

1. Copy the exact fully-qualified class name from the message and verify it against your class (no typos, correct package).
2. Ensure the jar containing the class is on the runtime classpath (not provided/compile-only).
3. Prefer passing a Class instance or a pre-built instance in programmatic configuration instead of a String name.
4. If the class is loaded by a child classloader, pass the instance directly so Class.forName on the app classloader is bypassed.

Example fix

// before
props.put("hibernate.session_factory.session_scoped_interceptor", "com.acme.MyIntercepter"); // typo

// after
props.put("hibernate.session_factory.session_scoped_interceptor", "com.acme.MyInterceptor");

// fail early with your own message instead of during bootstrap
String fqcn = (String) settings.get(SETTING_KEY);
try {
    Class.forName(fqcn, true, Thread.currentThread().getContextClassLoader());
} catch (ClassNotFoundException cnfe) {
    throw new IllegalStateException("Setting " + SETTING_KEY + " points to missing class " + fqcn, cnfe);
}

When it happens

Trigger: Passing a misspelled or non-fully-qualified class name in a setting consumed by loadSettingInstance (for example an interceptor/observer setting supplied via configurationValues) when the service registry is null during early boot; the class exists but sits in a jar not visible to the application classloader.

Common situations: Typo in a fully-qualified class name in persistence.xml or a properties map; refactoring moved/renamed the class but the config string was not updated; the implementation jar was declared provided-scope and is absent at runtime.

Related errors

• Unable to load class {}
• Duplicate generator name '%s'; you will likely want to set t
• Duplicate generator name %s; you will likely want to set the
• Unable to load class [" + className + "]
• Unknown TcclLookupPrecedence - {}

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