hibernate/hibernate-orm · error · FunctionArgumentException

Argument '%s' of 'fk()' function is not a single-valued asso

Error message

Argument '%s' of 'fk()' function is not a single-valued association

What it means

Error "Argument '%s' of 'fk()' function is not a single-valued association" thrown in hibernate/hibernate-orm.

Source

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

			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()
					)
			);

		}
		return new SqmFkExpression<>( sqmPath );
	}

	@Override
	public SqmMapEntryReference<?, ?> visitMapEntrySelection(HqlParser.MapEntrySelectionContext ctx) {
		return new SqmMapEntryReference<>(
				consumePluralAttributeReference( ctx.path() ),
				nodeBuilder()
		);
	}

View on GitHub (pinned to fad1729dce)

Solutions

1. fk() requires a single-valued (many-to-one/one-to-one) association path. Pass a singular association reference, not a collection, and check the path resolves to a to-one association.

When it happens

Trigger: fk() is applied to something that is not a single-valued association: Argument '<value>' of 'fk()' function is not a single-valued association

Common situations: Using fk() on basic attributes or collection-valued associations instead of many-to-one/one-to-one references.

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