hibernate/hibernate-orm · error · IllegalArgumentException

Named native query definition object is null

Error message

Named native query definition object is null

What it means

Same guard as for HQL queries but on the native side: addNamedNativeQuery(...) was called with a null NamedNativeQueryDefinition during metadata collection. The definition is the only carrier of the SQL string, result-set mapping and hints, so nothing can be registered from null. Bootstrap fails immediately.

Source

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

	}

	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// 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. Null-check the definition right before registration and fail with a message naming the producer
2. Fix the builder: an incompletely configured NamedNativeQueryDefinitionBuilder is the usual source of null
3. Audit META-INF/services contributor registrations after upgrading Hibernate

Example fix

// before
collector.addNamedNativeQuery( buildNativeQuery( descriptor ) );

// after
final NamedNativeQueryDefinition<?> def = buildNativeQuery( descriptor );
if ( def == null ) {
    throw new IllegalStateException( "No native-query definition built for " + descriptor );
}
collector.addNamedNativeQuery( def );

NamedNativeQueryDefinition<?> def = buildNativeQuery( source );
if ( def == null || def.getRegistrationName() == null ) {
    throw new IllegalStateException( "Invalid native-query definition from: " + source );
}
collector.addNamedNativeQuery( def );

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

try {
    metadata.buildSessionFactory();
} catch ( IllegalArgumentException e ) {
    if ( e.getMessage() != null && e.getMessage().contains( "native query definition object is null" ) ) {
        throw new IllegalStateException( "Broken native-query contributor: " + e.getMessage(), e );
    }
    throw e;
}

When it happens

Trigger: A custom MetadataContributor or programmatic bootstrap path calling addNamedNativeQuery(null); a NamedNativeQueryDefinitionBuilder whose build() result was forwarded without a null check after missing configuration.

Common situations: Libraries that register native queries from config files or JSON descriptors, contributor code written against older Hibernate versions, and half-initialized builders after refactors.

Related errors

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

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