hibernate/hibernate-orm · error · IllegalArgumentException

Named query definition is null

Error message

Named query definition is null

What it means

Hibernate registers every named HQL query (from @NamedQuery, orm.xml/hbm.xml <query>, or programmatic contributions) in the in-flight metadata collector during SessionFactory bootstrap. This exception means addNamedQuery(...) received a null NamedHqlQueryDefinition, i.e. some mapping contributor produced no definition object at all. The collector never stores null definitions, so bootstrap aborts immediately.

Source

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

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Named query handling

	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 );
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Null-check the definition right before registering it and throw a clear error naming the contributor that produced it
2. Trace the null to its source: usually a NamedHqlQueryDefinitionBuilder invoked without setHqlString/setName — complete the builder call chain
3. If you have no custom contributor, bisect third-party jars that register META-INF/services/org.hibernate.boot.spi.MetadataContributor and upgrade or remove the stale one
4. Re-run bootstrap after each change; this guard always fails the whole SessionFactory build

Example fix

// before
collector.addNamedQuery( buildNamedQuery( props ) );

// after
final NamedHqlQueryDefinition<?> def = buildNamedQuery( props );
if ( def == null ) {
    throw new IllegalStateException( "Query contributor returned no definition for: " + props );
}
collector.addNamedQuery( def );

NamedHqlQueryDefinition<?> def = buildNamedQuery( source );
if ( def == null || def.getRegistrationName() == null ) {
    throw new IllegalStateException( "Invalid named-query definition produced from: " + source );
}
collector.addNamedQuery( def );

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

try {
    sessionFactory = metadata.buildSessionFactory();
} catch ( IllegalArgumentException e ) {
    if ( e.getMessage() != null && e.getMessage().contains( "Named query definition" ) ) {
        // a mapping contributor passed a null definition — fix the producer, not the caller
        throw new IllegalStateException( "Broken named-query contributor: " + e.getMessage(), e );
    }
    throw e;
}

When it happens

Trigger: Calling InFlightMetadataCollector.addNamedQuery(null) from custom code, or a custom org.hibernate.boot.spi.MetadataContributor forwarding the result of a builder (e.g. NamedHqlQueryDefinitionBuilder) that returned null because it was incompletely configured.

Common situations: Hand-written MetadataContributor extensions, programmatic bootstrap that builds query definitions from config files where a missing entry yields null, and Hibernate major upgrades where contributor/builder APIs changed and stale implementations now pass null.

Related errors

• Named query definition name is null: %s
• Duplicate named query '%s'
• Named native query definition object is null
• Result-set mapping was null
• Import name or entity name is null

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