hibernate/hibernate-orm · error · FunctionArgumentException

Argument '{}' of 'naturalid()' is a '{}' and does not have a

Error message

Argument '{}' of 'naturalid()' is a '{}' and does not have a natural id

What it means

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

Source

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

	@Override
	public SqmPath<?> visitEntityNaturalIdExpression(HqlParser.EntityNaturalIdExpressionContext ctx) {
		return visitEntityNaturalIdReference( ctx.entityNaturalIdReference() );
	}

	@Override
	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" );

View on GitHub (pinned to fad1729dce)

Solutions

1. The argument passed to naturalid() resolves to a type that declares no @NaturalId. Add a @NaturalId attribute to the entity, or call naturalid() on an entity that actually has one.

When it happens

Trigger: The naturalid() function is misused: Argument '<value>' of 'naturalid()' is a '<value>' and does not have a 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/eb5173be904d6941. Report an issue: GitHub.