hibernate/hibernate-orm · error · QueryException

Illegal interpolation '%s' ('%s' is a field alias)

Error message

Illegal interpolation '%s' ('%s' is a field alias)

What it means

For a collection alias in a legacy native query, interpolating '{alias.*}' asks Hibernate to render the persister's full select fragment. SQLQueryParser.resolveCollectionProperties refuses when the alias has explicit field results (a property->column-alias map from <return-property>/addProperty/@FieldResult), because '*' would conflict with the hand-declared column aliases — it throws QueryException labeling the interpolation illegal.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/sql/internal/SQLQueryParser.java:226

			case "h-catalog":
				if ( defaultCatalog != null ) {
					result.append( defaultCatalog.render(dialect) );
					result.append( "." );
				}
				break;
			default:
				throw new QueryException( "Unknown placeholder ", token);
		}
	}

	private String resolveCollectionProperties(String aliasName, String propertyName, String token) {
		final var fieldResults = context.getPropertyResultsMap( aliasName );
		final var collectionPersister = context.getCollectionPersister( aliasName );
		final String collectionSuffix = context.getCollectionSuffix( aliasName );
		switch ( propertyName ) {
			case "*":
				if ( !fieldResults.isEmpty() ) {
					throw new QueryException(
							"Illegal interpolation '%s' ('%s' is a field alias)"
									.formatted( token, aliasName ),
							originalQueryString
					);
				}
				aliasesFound++;
				return collectionPersister.selectFragment( aliasName, collectionSuffix )
						+ ", " + resolveProperties( aliasName, propertyName, token );
			case "element.*":
				return resolveProperties( aliasName, "*", token );
			default:
				// Let return-properties override whatever the persister has for aliases.
				String[] columnAliases = fieldResults.get( propertyName );
				if ( columnAliases == null ) {
					columnAliases =
							collectionPersister.getCollectionPropertyColumnAliases( propertyName, collectionSuffix );
				}
				validate( aliasName, propertyName, columnAliases, token );

View on GitHub (pinned to fad1729dce)

Solutions

1. Drop the explicit property/field results for that alias so '*' is legal again.
2. Or stop using '{alias.*}' and reference the mapped properties explicitly in the SQL ({alias.prop} for each).
3. Modernize the mapping away from hbm.xml interpolation to @SqlResultSetMapping or entity association fetching.

Example fix

-- before (mapping declares return-property entries for alias 'items')
select {i.*}, {items.*} from item i, order_items items ...

-- after: interpolate only when no explicit field aliases exist, or list them
select {i.*}, {items.itemId} {items.amount} from item i, order_items items ...

// before finalizing a legacy native query: if the alias has explicit property results, forbid {alias.*}
boolean hasFieldResults = mappingContext.hasPropertyResults("items"); // mirrors getPropertyResultsMap(aliasName).isEmpty()
if (hasFieldResults && sql.contains("{items.*}")) throw new IllegalStateException("Alias 'items' declares field results — {items.*} interpolation is illegal");

try { query.list(); } catch (org.hibernate.QueryException e) { /* on 'Illegal interpolation', remove {alias.*} or drop the explicit property aliases */ throw e; }

When it happens

Trigger: A native query mixing 'select {items.*} ...' with a mapping that declares property results for alias 'items' — e.g. hbm.xml <load-collection alias="items"> with nested <return-property> entries, or programmatic .addProperty("amount", "itm_amount") on a collection return.

Common situations: Legacy hbm.xml resultset mappings where column aliases were customized per property; partial modernization that keeps {alias.*} in the SQL while adding explicit field mappings; copying entity-style mappings onto collection joins.

Related errors

• Owner alias [{ownerAlias}] is unknown for alias [{alias}]
• Unknown placeholder {token}
• No column for interpolation '%s'
• Multiple columns for interpolation '%s' ('%s' is mapped to %
• Duplicate collection definition '%s'

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