hibernate/hibernate-orm · error · IllegalStateException

alias for Map dynamic instantiation argument cannot be null

Error message

alias for Map dynamic instantiation argument cannot be null

What it means

Thrown while building the result assembler for an HQL dynamic Map instantiation (`select new map(...)`). Each selected argument becomes one map entry, keyed by that argument's alias, so every argument must carry an `as <alias>`. A null alias means an argument was selected without an alias and therefore has no map key. The higher-level check in DynamicInstantiationResultImpl (error 3182) normally fires first during query-plan creation, so this assembler-level message surfaces only through paths that construct DynamicInstantiationAssemblerMapImpl directly.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/sql/results/graph/instantiation/internal/DynamicInstantiationAssemblerMapImpl.java:38

 * A QueryResultAssembler implementation representing handling for dynamic-
 * instantiations targeting a Map, e.g.`select new map( pers.name, pers.dateOfBirth ) ...`
 *
 * @author Steve Ebersole
 */
public class DynamicInstantiationAssemblerMapImpl implements DomainResultAssembler<Map<?,?>> {
	private final JavaType<Map<?,?>> mapJavaType;
	private final List<ArgumentReader<?>> argumentReaders;

	public DynamicInstantiationAssemblerMapImpl(
			JavaType<Map<?,?>> mapJavaType,
			List<ArgumentReader<?>> argumentReaders) {
		this.mapJavaType = mapJavaType;
		this.argumentReaders = argumentReaders;

		final Set<String> aliases = new HashSet<>();
		for ( var argumentReader : argumentReaders ) {
			if ( argumentReader.getAlias() == null ) {
				throw new IllegalStateException( "alias for Map dynamic instantiation argument cannot be null" );
			}

			if ( ! aliases.add( argumentReader.getAlias() ) ) {
				throw new IllegalStateException( "Encountered duplicate alias for Map dynamic instantiation argument [" + argumentReader.getAlias() + "]" );
			}
		}
	}

	private DynamicInstantiationAssemblerMapImpl(
			List<ArgumentReader<?>> argumentReaders,
			JavaType<Map<?,?>> mapJavaType) {
		this.mapJavaType = mapJavaType;
		this.argumentReaders = argumentReaders;
	}

	@Override
	public JavaType<Map<?,?>> getAssembledJavaType() {
		return mapJavaType;

View on GitHub (pinned to fad1729dce)

Solutions

Add a unique alias to every argument: `select new map(e.id as id, e.name as name) from Employee e`
Re-run the query; the check happens at plan creation, so fixing the HQL is sufficient
If building the SQM tree programmatically, call `selection.alias("...")` on every selection before execution

Example fix

// before
select new map(e.id, e.name) from Employee e
// after
select new map(e.id as id, e.name as name) from Employee e

Defensive patterns

Strategy: validation

Validate before calling

// Before executing, assert every selection in the map instantiation carries an alias (HQL smoke check)
String hql = "select new map(e.id as id, e.name as name) from Employee e";
String args = hql.substring(hql.indexOf('(') + 1, hql.lastIndexOf(')'));
for (String arg : args.split(",")) {
    if (!arg.trim().matches("(?is).*\\bas\\s+\\w+\\s*$")) {
        throw new IllegalArgumentException("Unaliased argument in new map(...): " + arg);
    }
}

Prevention

Alias every argument the moment you write `new map(...)` - treat `as` as mandatory syntax
Keep a startup/integration test per named query so missing aliases fail the build, not production
Prefer explicit aliases over relying on generated ones for any dynamic instantiation

When it happens

Trigger: Running `select new map(e.id, e.name) from Employee e` (no `as` clauses); `select new map(count(e), sum(e.salary)) from Employee e` (aggregate expressions without aliases); programmatically building an SQM select with DynamicInstantiationNature.MAP while one SqmSelection has a null alias.

Common situations: Porting a query from `new list(...)` (aliases optional) to `new map(...)` (aliases mandatory); adding an extra unaliased expression to an existing map instantiation during refactoring; queries written against Hibernate 5 where the failure surfaced at a different layer with a different message.

Related errors

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