hibernate/hibernate-orm · error · IllegalArgumentException

Named native query definition name is null: {}

Error message

Named native query definition name is null: {}

What it means

A native query definition arrived with a null registration name. The exception text embeds the raw SQL of the offending query so the broken declaration can be found by search. Without a name the query can never be looked up, so the collector rejects it and bootstrap stops.

Source

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

	// Named native-query handling

	@Override
	public NamedNativeQueryDefinition<?> getNamedNativeQueryMapping(String name) {
		return namedNativeQueryMap.get( name );
	}

	@Override
	public void visitNamedNativeQueryDefinitions(Consumer<NamedNativeQueryDefinition<?>> definitionConsumer) {
		namedNativeQueryMap.values().forEach( definitionConsumer );
	}

	@Override
	public void addNamedNativeQuery(NamedNativeQueryDefinition<?> def) {
		if ( def == null ) {
			throw new IllegalArgumentException( "Named native query definition object is null" );
		}
		else if ( def.getRegistrationName() == null ) {
			throw new IllegalArgumentException( "Named native query definition name is null: " + def.getSqlQueryString() );
		}
		else if ( !defaultNamedNativeQueryNames.contains( def.getRegistrationName() ) ) {
			applyNamedNativeQuery( def.getRegistrationName(), def );
		}
	}

	private void applyNamedNativeQuery(String name, NamedNativeQueryDefinition<?> query) {
		checkQueryName( name );
		namedNativeQueryMap.put( name.intern(), query );
	}

	@Override
	public void addDefaultNamedNativeQuery(NamedNativeQueryDefinition<?> query) {
		applyNamedNativeQuery( query.getRegistrationName(), query );
		defaultNamedNativeQueryNames.add( query.getRegistrationName() );
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. Copy the SQL from the message into a project search to find the declaration
2. XML: add the required name attribute to the <named-native-query>/<sql-query> element
3. Builder: call setName(...) before build()
4. Validate orm.xml against the persistence schema in CI so missing attributes are caught statically

Example fix

<!-- before -->
<named-native-query>
    <query>SELECT * FROM users WHERE active = 1</query>
</named-native-query>

<!-- after -->
<named-native-query name="User.findActiveNative">
    <query>SELECT * FROM users WHERE active = 1</query>
</named-native-query>

if ( def == null || def.getRegistrationName() == null || def.getRegistrationName().isBlank() ) {
    throw new IllegalStateException( "Native query missing registration name; sql=" + def );
}
collector.addNamedNativeQuery( def );

static boolean hasRegistrationName( NamedNativeQueryDefinition<?> def ) {
    return def != null && def.getRegistrationName() != null && !def.getRegistrationName().isBlank();
}

try {
    metadata.buildSessionFactory();
} catch ( IllegalArgumentException e ) {
    if ( e.getMessage() != null && e.getMessage().startsWith( "Named native query definition name is null" ) ) {
        // message contains the raw SQL — search the project for it
        throw new IllegalStateException( "Nameless native query: " + e.getMessage(), e );
    }
    throw e;
}

When it happens

Trigger: An orm.xml <named-native-query> (or hbm.xml <sql-query>) element missing its name attribute; a NamedNativeQueryDefinitionBuilder used without setName(...); contributor code copying definitions and losing the name.

Common situations: Hand-edited XML mappings that no longer validate, migration tooling dropping attributes, and programmatically generated native queries whose names come from empty config values.

Related errors

• Named query definition name is null: %s
• Named native query definition object is null
• Result-set mapping name is null: {}
• Named query definition is null
• Duplicate named query '%s'

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