hibernate/hibernate-orm · error · IllegalArgumentException

Query hint `%s` is only relevant for ProcedureCall queries

Error message

Query hint `%s` is only relevant for ProcedureCall queries

What it means

Thrown by the base applyCallableFunctionHint (line 760) when the hint 'org.hibernate.callableFunction' is applied to anything that is not a ProcedureCall. The hint exists to mark a stored-procedure call as a FUNCTION call (invoked as {? = call fn(...)} with a return value instead of {call proc(...)}); AbstractCommonQueryContract cannot honor it, so it rejects the request. ProcedureCallImpl overrides these handlers; every other query type (HQL, native, criteria) hits the base throw.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java:761

	}

	protected void applyFollowOnStrategyHint(Object value) {
		//noinspection removal
		queryOptions.getLockOptions().setFollowOnStrategy( Locking.FollowOn.fromHint( value ) );
	}

	protected void applyFollowOnLockingHint(Boolean followOnLocking) {
		//noinspection deprecation
		DEPRECATION_LOGGER.deprecatedHint( HINT_FOLLOW_ON_LOCKING, HINT_FOLLOW_ON_STRATEGY );
		applyFollowOnStrategyHint( Locking.FollowOn.fromLegacyValue( followOnLocking ) );
	}

	protected void applySynchronizeSpacesHint(Object value) {
		throw new IllegalArgumentException( "Query spaces hint was specified for non-native query" );
	}

	protected void applyCallableFunctionHint(String hintName, Object value) {
		throw new IllegalArgumentException( String.format( ROOT,
				"Query hint `%s` is only relevant for ProcedureCall queries",
				hintName
		) );
	}

	protected void applyCallableFunctionTypeHint(String hintName, Object value) {
		throw new IllegalArgumentException( String.format( ROOT,
				"Query hint `%s` is only relevant for ProcedureCall queries",
				hintName
		) );
	}


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
	// Options
	@Override
	@Nullable
	public String getComment() {

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the hint from non-procedure queries
2. Use session.createStoredProcedureQuery(...) / procedure call syntax where the hint is honored (or annotate with @ProcedureNamedStoredProcedureQuery-style config using HibernateHints.HINT_CALLABLE_FUNCTION)
3. For calling DB functions in HQL use the function/procedure-call syntax of the query language, not this hint

Example fix

// before
Query q = session.createNativeQuery( "select fn_calculate(:x)" );
q.setHint( HibernateHints.HINT_CALLABLE_FUNCTION, true ); // throws

// after
StoredProcedureQuery q = em.createStoredProcedureQuery( "fn_calculate" );
q.registerStoredProcedureParameter( 1, Integer.class, ParameterMode.IN );
q.setHint( HibernateHints.HINT_CALLABLE_FUNCTION, true ); // OK on ProcedureCall

if ( query instanceof org.hibernate.procedure.ProcedureCall ) {
    query.setHint( HibernateHints.HINT_CALLABLE_FUNCTION, true );
} else {
    // plain queries don't take this hint: skip or use function syntax in HQL
}

static boolean isProcedureCall(jakarta.persistence.Query q) {
    return q instanceof org.hibernate.procedure.ProcedureCall;
}

When it happens

Trigger: session.createQuery(...).setHint("org.hibernate.callableFunction", true); or applying the hint inside a generic hint helper to a jakarta.persistence.Query that is actually HQL/native. Setting it on a StoredProcedureQuery obtained through an API that returns jakarta.persistence.Query but maps to a plain native query in this Hibernate version.

Common situations: Refactoring ProcedureCall code into a generic query factory; copying @QueryHints from a @NamedStoredProcedureQuery onto entity queries; using the hint as a 'function call' flag on native SQL calling a function instead of using the proper function syntax.

Related errors

• Named query hint [" + hintName + "] is not a boolean: " + qu
• Named query hint [" + hintName + "] is not an integer: " + q
• Unable to interpret CacheMode in named query hint: " + query
• Unable to generate set of all hints - {}
• Incorrect value for query hint: {hintName}

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