hibernate/hibernate-orm · error · IllegalArgumentException

Specified attribute [%s.%s] must be basic: %s

Error message

Specified attribute [%s.%s] must be basic: %s

What it means

Error "Specified attribute [%s.%s] must be basic: %s" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/results/internal/dynamic/DynamicResultBuilderAttribute.java:42

/**
 * DynamicResultBuilder based on a named mapped attribute
 *
 * @author Steve Ebersole
 */
public class DynamicResultBuilderAttribute implements DynamicResultBuilder, NativeQuery.ReturnProperty {
	private final BasicAttributeMapping attributeMapping;
	private final String columnAlias;
	private final String entityName;
	private final String attributePath;

	public DynamicResultBuilderAttribute(
			SingularAttributeMapping attributeMapping,
			String columnAlias,
			String entityName,
			String attributePath) {
		final boolean allowable = attributeMapping instanceof BasicAttributeMapping;
		if ( !allowable ) {
			throw new IllegalArgumentException(
					String.format(
							Locale.ROOT,
							"Specified attribute [%s.%s] must be basic: %s",
							entityName,
							attributePath,
							attributeMapping
					)
			);
		}

		this.attributeMapping = (BasicAttributeMapping) attributeMapping;
		this.columnAlias = columnAlias;
		this.entityName = entityName;
		this.attributePath = attributePath;
	}

	@Override
	public Class<?> getJavaType() {

View on GitHub (pinned to fad1729dce)

Solutions

1. The specified attribute must be basic. Use a column-mapped basic attribute.

When it happens

Trigger: A runtime precondition of the Hibernate query API is violated: Specified attribute [<value>.<value>] must be basic: <value>

Common situations: Application code or configuration calls the query API in a way that violates its documented contract; the interpolated values in the message identify the offending input.

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