hibernate/hibernate-orm · error · IllegalArgumentException

Import name or entity name is null

Error message

Import name or entity name is null

What it means

addImport(...) registers the mapping from an unqualified HQL entity name (or an explicit hbm.xml <import rename="...">) to the entity name. This IllegalArgumentException means importName or className was null — the import table cannot hold partial entries. Almost always raised from programmatic/contributor code, not plain annotation applications.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/boot/internal/InFlightMetadataCollectorImpl.java:878

			sqlResultSetMappingMap.remove( name );
		}
		applyResultSetMapping( definition );
		defaultSqlResultSetMappingNames.add( name );
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// imports

	@Override
	public Map<String,String> getImports() {
		return imports;
	}

	@Override
	public void addImport(String importName, String className) {
		if ( importName == null || className == null ) {
			throw new IllegalArgumentException( "Import name or entity name is null" );
		}
		BOOT_LOGGER.importEntry( importName, className );
		final String old = imports.put( importName, className);
		if ( old != null ) {
			BOOT_LOGGER.importOverrodePrevious( importName, old );
		}
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Table handling

	@Override
	public Table addTable(
			String schemaName,
			String catalogName,
			String name,
			String subselectFragment,

View on GitHub (pinned to fad1729dce)

Solutions

1. Guard both arguments with null checks before calling addImport
2. Log the (importName, className) pair at registration so the broken entry is identifiable
3. If the values come from config, validate them at load time and report the offending key

Example fix

// before
collector.addImport( entry.get( "rename" ), entry.get( "class" ) );

// after
final String rename = entry.get( "rename" );
final String className = entry.get( "class" );
if ( rename == null || className == null ) {
    throw new IllegalStateException( "Incomplete <import> entry: " + entry );
}
collector.addImport( rename, className );

if ( importName == null || className == null ) {
    throw new IllegalStateException( "Incomplete import entry: rename=" + importName + ", class=" + className );
}
collector.addImport( importName, className );

static boolean isCompleteImport( String importName, String className ) {
    return importName != null && !importName.isBlank()
            && className != null && !className.isBlank();
}

try {
    metadata.buildSessionFactory();
} catch ( IllegalArgumentException e ) {
    if ( e.getMessage() != null && e.getMessage().contains( "Import name or entity name is null" ) ) {
        throw new IllegalStateException( "Incomplete entity import registered by a contributor", e );
    }
    throw e;
}

When it happens

Trigger: Calling metadataCollector.addImport(name, null) or addImport(null, cls) from custom code; dynamic-map entities whose entity-name resolution returned null; broken <import> handling in custom binders.

Common situations: Custom MetadataContributors adding HQL short names, tooling that mirrors hbm.xml <import> elements, and upgrades that changed dynamic-map name handling.

Related errors

• Named query definition is null
• Named native query definition object is null
• Result-set mapping was null
• Column with logical name '%s' in table '%s' cannot be mapped
• Named query definition name is null: %s

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