hibernate/hibernate-orm · error · IllegalArgumentException

Named query definition name is null: %s

Error message

Named query definition name is null: %s

What it means

A named query definition reached the collector with a null registration name — the key under which session.createNamedQuery(name) later resolves it. The message appends the raw HQL string precisely so the broken declaration can be found by search. Hibernate cannot register a query without a lookup key, so bootstrap fails.

Source

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

	public NamedHqlQueryDefinition<?> getNamedHqlQueryMapping(String name) {
		if ( name == null ) {
			throw new IllegalArgumentException( "null is not a valid query name" );
		}
		return namedQueryMap.get( name );
	}

	@Override
	public void visitNamedHqlQueryDefinitions(Consumer<NamedHqlQueryDefinition<?>> definitionConsumer) {
		namedQueryMap.values().forEach( definitionConsumer );
	}

	@Override
	public void addNamedQuery(NamedHqlQueryDefinition<?> def) {
		if ( def == null ) {
			throw new IllegalArgumentException( "Named query definition is null" );
		}
		else if ( def.getRegistrationName() == null ) {
			throw new IllegalArgumentException( "Named query definition name is null: " + def.getHqlString() );
		}
		else if ( !defaultNamedQueryNames.contains( def.getRegistrationName() ) ) {
			applyNamedQuery( def.getRegistrationName(), def );
		}
	}

	private void applyNamedQuery(String name, NamedHqlQueryDefinition<?> query) {
		checkQueryName( name );
		namedQueryMap.put( name.intern(), query );
	}

	private void checkQueryName(String name) throws DuplicateMappingException {
		if ( namedQueryMap.containsKey( name ) || namedNativeQueryMap.containsKey( name ) ) {
			throw new DuplicateMappingException( DuplicateMappingException.Type.QUERY, name );
		}
	}

	@Override

View on GitHub (pinned to fad1729dce)

Solutions

1. Copy the HQL shown in the message into a project-wide search to locate the declaration
2. orm.xml: add the name attribute to the <query> element
3. Builder-based registration: call setName(...) before passing the definition to the collector
4. Guard programmatic definitions with Objects.requireNonNull(def.getRegistrationName()) at build time

Example fix

// before — no name set
collector.addNamedQuery( new NamedHqlQueryDefinitionBuilder()
        .setHqlString( "from User u where u.active = true" )
        .build() );

// after
collector.addNamedQuery( new NamedHqlQueryDefinitionBuilder()
        .setName( "User.findActive" )
        .setHqlString( "from User u where u.active = true" )
        .build() );

if ( def == null || def.getRegistrationName() == null || def.getRegistrationName().isBlank() ) {
    throw new IllegalStateException( "Named query missing registration name; hql=" + def );
}
collector.addNamedQuery( def );

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

try {
    metadata.buildSessionFactory();
} catch ( IllegalArgumentException e ) {
    if ( e.getMessage() != null && e.getMessage().startsWith( "Named query definition name is null" ) ) {
        // message contains the HQL — use it to find the broken declaration
        throw new IllegalStateException( "Nameless named query: " + e.getMessage(), e );
    }
    throw e;
}

When it happens

Trigger: A NamedHqlQueryDefinitionBuilder used without setName(...); an orm.xml <query> element missing the required name attribute; a custom contributor that copies definitions and drops the name field.

Common situations: Hand-edited orm.xml files that no longer pass schema validation, Jakarta-migration tooling rewriting mapping files and dropping attributes, and programmatic bootstrap where the name comes from config and is silently empty.

Related errors

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

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