hibernate/hibernate-orm · error · FunctionArgumentException

Argument '{}' of 'naturalid()' does not resolve to an entity

Error message

Argument '{}' of 'naturalid()' does not resolve to an entity type

What it means

Error "Argument '{}' of 'naturalid()' does not resolve to an entity type" thrown in hibernate/hibernate-orm.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/hql/internal/SemanticQueryBuilder.java:3609

			if ( attributes == null ) {
				throw new FunctionArgumentException( "Argument '" + sqmPath.getNavigablePath()
							+ "' of 'naturalid()' is a '" + identifiableType.getTypeName()
							+ "' and does not have a natural id"
				);
			}
			else if ( attributes.size() > 1 ) {
				throw new FunctionArgumentException( "Argument '" + sqmPath.getNavigablePath()
							+ "' of 'naturalid()' is a '" + identifiableType.getTypeName()
							+ "' and has a composite natural id"
				);
			}

			final var naturalIdAttribute =
					(SingularPersistentAttribute<? super U, ?>)
							attributes.get( 0 );
			return sqmPath.get( naturalIdAttribute );
		}
		throw new FunctionArgumentException( "Argument '" + sqmPath.getNavigablePath()
				+ "' of 'naturalid()' does not resolve to an entity type" );
	}

	@Override
	public SqmFkExpression<?> visitToOneFkReference(HqlParser.ToOneFkReferenceContext ctx) {
		final var sqmPath = consumeDomainPath( (HqlParser.PathContext) ctx.getChild( 2 ) );
		final var toOneReference = sqmPath.getResolvedModel();
		final boolean validToOneRef =
				toOneReference.getBindableType() == Bindable.BindableType.SINGULAR_ATTRIBUTE
						&& toOneReference.getPathType() instanceof SqmEntityDomainType<?>;
		if ( !validToOneRef ) {
			throw new FunctionArgumentException(
					String.format(
							Locale.ROOT,
							"Argument '%s' of 'fk()' function is not a single-valued association",
							sqmPath.getNavigablePath()
					)
			);

View on GitHub (pinned to fad1729dce)

Solutions

1. The argument of naturalid() must resolve to an entity type. Verify the path or alias passed to naturalid() refers to a mapped entity and is spelled correctly in the HQL.

When it happens

Trigger: A name/path expected to denote an entity type does not: Argument '<value>' of 'naturalid()' does not resolve to an entity type

Common situations: Passing non-entity arguments to version()/naturalid(), or a TREAT target / entity name that is not a mapped entity; commonly a typo or unmapped class.

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