hibernate/hibernate-orm · error · FunctionArgumentException

Argument '{}' of 'naturalid()' is a '{}' and has a composite

Error message

Argument '{}' of 'naturalid()' is a '{}' and has a composite natural id

What it means

Error "Argument '{}' of 'naturalid()' is a '{}' and has a composite natural id" thrown in hibernate/hibernate-orm.

Source

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

	public SqmPath<?> visitEntityNaturalIdReference(HqlParser.EntityNaturalIdReferenceContext ctx) {
		if ( ctx.pathContinuation() != null ) {
			throw new UnsupportedOperationException( "Path continuation from 'naturalid()' reference not yet implemented" );
		}
		return handleNaturalIdPath( consumeDomainPath( ctx.path() ) );
	}

	private static <U> SqmPath<?> handleNaturalIdPath(SqmPath<U> sqmPath) {
		if ( sqmPath.getReferencedPathSource().getPathType()
				instanceof AbstractIdentifiableType<U> identifiableType ) {
			final var attributes = identifiableType.findNaturalIdAttributes();
			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();

View on GitHub (pinned to fad1729dce)

Solutions

1. naturalid() does not support composite natural ids. Reference the individual natural-id attributes explicitly in the query instead of using naturalid() on an entity with a composite natural id.

When it happens

Trigger: The naturalid() function is misused: Argument '<value>' of 'naturalid()' is a '<value>' and has a composite natural id

Common situations: Calling naturalid() on entities without a @NaturalId, with a composite natural id, or continuing a path from it.

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