hibernate/hibernate-orm · error · UnsupportedOperationException

Path continuation from 'naturalid()' reference not yet imple

Error message

Path continuation from 'naturalid()' reference not yet implemented

What it means

Error "Path continuation from 'naturalid()' reference not yet implemented" thrown in hibernate/hibernate-orm.

Source

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

			final var versionAttribute = identifiableType.findVersionAttribute();
			assert versionAttribute != null; // Safe, we just checked hasVersionAttribute()
			return sqmPath.get( versionAttribute );
		}
		else {
			throw new FunctionArgumentException( "Argument '" + sqmPath.getNavigablePath()
						+ "' of 'version()' does not resolve to an entity type" );
		}
	}

	@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"

View on GitHub (pinned to fad1729dce)

Solutions

1. Do not continue a path past a naturalid() reference; naturalid() must be the terminal step of the path. Rewrite the HQL so the path ends at naturalid(), or join/load the entity and navigate its attributes instead.

When it happens

Trigger: The naturalid() function is misused: Path continuation from 'naturalid()' reference not yet implemented

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/955282f18de2127d. Report an issue: GitHub.