{"record":{"id":"d2c64355b345b152","repo":"hibernate/hibernate-orm","slug":"query-hint-s-is-only-relevant-for-procedurecall","errorCode":null,"errorMessage":"Query hint `%s` is only relevant for ProcedureCall queries","messagePattern":"Query hint `(.+?)` is only relevant for ProcedureCall queries","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java","lineNumber":761,"sourceCode":"\t}\n\n\tprotected void applyFollowOnStrategyHint(Object value) {\n\t\t//noinspection removal\n\t\tqueryOptions.getLockOptions().setFollowOnStrategy( Locking.FollowOn.fromHint( value ) );\n\t}\n\n\tprotected void applyFollowOnLockingHint(Boolean followOnLocking) {\n\t\t//noinspection deprecation\n\t\tDEPRECATION_LOGGER.deprecatedHint( HINT_FOLLOW_ON_LOCKING, HINT_FOLLOW_ON_STRATEGY );\n\t\tapplyFollowOnStrategyHint( Locking.FollowOn.fromLegacyValue( followOnLocking ) );\n\t}\n\n\tprotected void applySynchronizeSpacesHint(Object value) {\n\t\tthrow new IllegalArgumentException( \"Query spaces hint was specified for non-native query\" );\n\t}\n\n\tprotected void applyCallableFunctionHint(String hintName, Object value) {\n\t\tthrow new IllegalArgumentException( String.format( ROOT,\n\t\t\t\t\"Query hint `%s` is only relevant for ProcedureCall queries\",\n\t\t\t\thintName\n\t\t) );\n\t}\n\n\tprotected void applyCallableFunctionTypeHint(String hintName, Object value) {\n\t\tthrow new IllegalArgumentException( String.format( ROOT,\n\t\t\t\t\"Query hint `%s` is only relevant for ProcedureCall queries\",\n\t\t\t\thintName\n\t\t) );\n\t}\n\n\n\t// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\n\t// Options\n\t@Override\n\t@Nullable\n\tpublic String getComment() {","sourceCodeStart":743,"sourceCodeEnd":779,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java#L743-L779","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Remove the hint from non-procedure queries","Use session.createStoredProcedureQuery(...) / procedure call syntax where the hint is honored (or annotate with @ProcedureNamedStoredProcedureQuery-style config using HibernateHints.HINT_CALLABLE_FUNCTION)","For calling DB functions in HQL use the function/procedure-call syntax of the query language, not this hint"],"exampleFix":"// before\nQuery q = session.createNativeQuery( \"select fn_calculate(:x)\" );\nq.setHint( HibernateHints.HINT_CALLABLE_FUNCTION, true ); // throws\n\n// after\nStoredProcedureQuery q = em.createStoredProcedureQuery( \"fn_calculate\" );\nq.registerStoredProcedureParameter( 1, Integer.class, ParameterMode.IN );\nq.setHint( HibernateHints.HINT_CALLABLE_FUNCTION, true ); // OK on ProcedureCall","handlingStrategy":"validation","validationCode":"if ( query instanceof org.hibernate.procedure.ProcedureCall ) {\n    query.setHint( HibernateHints.HINT_CALLABLE_FUNCTION, true );\n} else {\n    // plain queries don't take this hint: skip or use function syntax in HQL\n}","typeGuard":"static boolean isProcedureCall(jakarta.persistence.Query q) {\n    return q instanceof org.hibernate.procedure.ProcedureCall;\n}","tryCatchPattern":null,"preventionTips":["Store procedure-only hints in a set applied exclusively to StoredProcedureQuery instances","Create function calls via em.createStoredProcedureQuery + the hint, never via generic queries","Assert query type before applying hints in framework interceptors"],"tags":["hibernate","stored-procedures","query-hints","procedure-call","function-call"],"backgroundTag":"query-hint-wrong-query-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}