hibernate/hibernate-orm · error · IllegalArgumentException

The specified class cannot be null

Error message

The specified class cannot be null

What it means

Configuration.addClass(Class) resolves the .hbm.xml mapping file for a class as a classpath resource (class name with '.' replaced by '/' plus ".hbm.xml"). A null class cannot name a resource, so Hibernate rejects it immediately with IllegalArgumentException. This is a fail-fast contract check on the single argument.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/cfg/Configuration.java:760

		return this;
	}

	/**
	 * Read a mapping as an application resource using the convention that a class
	 * named {@code foo.bar.Foo} is mapped by a file {@code foo/bar/Foo.hbm.xml}
	 * which can be resolved as a {@linkplain ClassLoader#getResource(String)
	 * classpath resource}.
	 *
	 * @param entityClass The mapped class
	 *
	 * @return {@code this} for method chaining
	 *
	 * @throws MappingException Indicates problems locating the resource or
	 * processing the contained mapping document.
	 */
	public Configuration addClass(Class<?> entityClass) throws MappingException {
		if ( entityClass == null ) {
			throw new IllegalArgumentException( "The specified class cannot be null" );
		}
		return addResource( hbmFileName( entityClass ) );
	}

	private static String hbmFileName(Class<?> entityClass) {
		return entityClass.getName().replace( '.', '/' )
			+ ".hbm.xml";
	}

	/**
	 * Read metadata from the annotations associated with this class.
	 *
	 * @param annotatedClass The class containing annotations
	 *
	 * @return {@code this} for method chaining
	 */
	public Configuration addAnnotatedClass(Class<?> annotatedClass) {
		metadataSources.addAnnotatedClass( annotatedClass );

View on GitHub (pinned to fad1729dce)

Solutions

1. Null-check the class before calling addClass
2. Fix the upstream lookup that produced null and log the class name that failed to resolve
3. Use addAnnotatedClass(Class) for annotation mappings, with the same null check

Example fix

// before
cfg.addClass(resolveEntity(name)); // resolveEntity returns null on miss -> throws

// after
Class<?> entity = resolveEntity(name);
if (entity == null) {
    throw new IllegalStateException("No entity class found for name: " + name);
}
cfg.addClass(entity);

Objects.requireNonNull(entityClass, "entityClass must not be null");
cfg.addClass(entityClass);

When it happens

Trigger: cfg.addClass(var) where var is null because a Class.forName lookup failed, a map or service returned null, or refactoring left an unset variable; loops that feed possibly-null classes into Configuration.

Common situations: Dynamic class scanning and string-driven configuration; migration scripts; test harnesses passing placeholders or unresolved class names.

Related errors

• <mapping/> named unexpected reference type
• Name of class to load cannot be null
• event name to resolve cannot be null
• Invalid access type " + propertyAccessType + " for property
• 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/07323d74525552ae. Report an issue: GitHub.