hibernate/hibernate-orm · error · IllegalArgumentException

null is not a valid query name

Error message

null is not a valid query name

What it means

getNamedHqlQueryMapping(name) looks up registered named HQL query definitions by name and rejects a null name immediately with IllegalArgumentException 'null is not a valid query name'. It signals that caller code passed an unresolved null query name into the lookup during metadata handling; a merely unknown name would return null without throwing.

Source

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

		return namedEntityGraphMap;
	}

	@Override
	public void addNamedEntityGraph(NamedEntityGraphDefinition definition) {
		final String name = definition.name();
		final var previous = namedEntityGraphMap.put( name, definition );
		if ( previous != null ) {
			throw new DuplicateMappingException( DuplicateMappingException.Type.NAMED_ENTITY_GRAPH, name );
		}
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// 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() ) ) {

View on GitHub (pinned to fad1729dce)

Solutions

1. Fix the caller on the stack trace so a real query name is resolved before the lookup
2. Guard with a null/empty check and fail with a descriptive error identifying the incomplete definition
3. Ensure every named query definition (annotation or XML) declares a name

Example fix

// before
var def = collector.getNamedHqlQueryMapping(queryName); // queryName is null

// after
if (queryName == null || queryName.isBlank()) {
    throw new IllegalArgumentException("named query definition lacks a name");
}
var def = collector.getNamedHqlQueryMapping(queryName);

if (queryName == null || queryName.isBlank()) {
    throw new IllegalArgumentException("named query definition lacks a name");
}
var definition = collector.getNamedHqlQueryMapping(queryName);

static boolean isQueryableQueryName(String name) {
    return name != null && !name.isBlank();
}

When it happens

Trigger: Integration or metadata-processing code calling getNamedHqlQueryMapping(null) - typically a query-name variable that failed to resolve, or processing of query definitions whose name attribute was missing so null flowed into the lookup (InFlightMetadataCollectorImpl.java:697-701).

Common situations: Custom named-query registration utilities; mappings where a <query> element or annotation lacks a name; conditional code paths that forget to set the name before use.

Related errors

• Filter definition object or name is null: %s
• Fetch profile object or name is null: %s
• null is not a valid generator name
• Id generator object or name is null
• Named query definition is null

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