hibernate/hibernate-orm · error · IllegalArgumentException

Result-set mapping was null

Error message

Result-set mapping was null

What it means

During bootstrap, addResultSetMapping(...) was handed a null NamedResultSetMappingDescriptor — the object that carries an @SqlResultSetMapping's column bindings. Nothing can be registered from null, so the build fails fast with this IllegalArgumentException.

Source

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

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// result-set mapping handling

	@Override
	public NamedResultSetMappingDescriptor getResultSetMapping(String name) {
		return sqlResultSetMappingMap.get( name );
	}

	@Override
	public void visitNamedResultSetMappingDefinition(Consumer<NamedResultSetMappingDescriptor> definitionConsumer) {
		sqlResultSetMappingMap.values().forEach( definitionConsumer );
	}

	@Override
	public void addResultSetMapping(NamedResultSetMappingDescriptor resultSetMappingDescriptor) {
		if ( resultSetMappingDescriptor == null ) {
			throw new IllegalArgumentException( "Result-set mapping was null" );
		}
		else {
			final String name = resultSetMappingDescriptor.getRegistrationName();
			if ( name == null ) {
				throw new IllegalArgumentException( "Result-set mapping name is null: " + resultSetMappingDescriptor );
			}
			else if ( !defaultSqlResultSetMappingNames.contains( name ) ) {
				applyResultSetMapping( resultSetMappingDescriptor );
			}
		}
	}

	public void applyResultSetMapping(NamedResultSetMappingDescriptor resultSetMappingDescriptor) {
		final var old = sqlResultSetMappingMap.put(
				resultSetMappingDescriptor.getRegistrationName(),
				resultSetMappingDescriptor
		);
		if ( old != null ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Null-check the descriptor before registration and fail with the originating configuration in the message
2. Fix the producer so a malformed entry raises its own descriptive error instead of returning null
3. Grep your codebase for addResultSetMapping callers — annotation users rarely hit this guard directly

Example fix

// before
collector.addResultSetMapping( buildResultSetMapping( entry ) );

// after
final NamedResultSetMappingDescriptor d = buildResultSetMapping( entry );
if ( d == null ) {
    throw new IllegalStateException( "No result-set mapping built for " + entry );
}
collector.addResultSetMapping( d );

NamedResultSetMappingDescriptor d = buildResultSetMapping( entry );
if ( d == null ) {
    throw new IllegalStateException( "No result-set mapping built for: " + entry );
}
collector.addResultSetMapping( d );

static boolean isRegistrableMapping( NamedResultSetMappingDescriptor d ) {
    return d != null && d.getRegistrationName() != null;
}

try {
    metadata.buildSessionFactory();
} catch ( IllegalArgumentException e ) {
    if ( e.getMessage() != null && e.getMessage().contains( "Result-set mapping was null" ) ) {
        throw new IllegalStateException( "Broken result-set-mapping contributor: " + e.getMessage(), e );
    }
    throw e;
}

When it happens

Trigger: A custom MetadataContributor or programmatic registration path passing null instead of a built descriptor — typically a builder that silently returned null for a malformed mapping entry.

Common situations: Libraries generating SqlResultSetMappings from configuration, refactors that changed how descriptors are constructed, and Hibernate major-version upgrades breaking contributor implementations.

Related errors

• Named query definition is null
• Named native query definition object is null
• Result-set mapping name is null: {}
• Duplicate SQL result set mapping '{}'
• Import name or entity name is null

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