{"record":{"id":"3ff85ea76d8d588b","repo":"hibernate/hibernate-orm","slug":"incorrect-value-for-query-hint-hintname","errorCode":null,"errorMessage":"Incorrect value for query hint: {hintName}","messagePattern":"Incorrect value for query hint: (.+?)","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java","lineNumber":606,"sourceCode":"\t\t\t\tcase HINT_FOLLOW_ON_LOCKING:\n\t\t\t\t\tapplyFollowOnLockingHint( getBoolean( value ) );\n\t\t\t\t\treturn true;\n\t\t\t\tcase HINT_CALLABLE_FUNCTION:\n\t\t\t\t\tapplyCallableFunctionHint( hintName, value );\n\t\t\t\t\treturn true;\n\t\t\t\tcase HINT_CALLABLE_FUNCTION_RETURN_TYPE:\n\t\t\t\t\tapplyCallableFunctionTypeHint( hintName, value );\n\t\t\t\tdefault:\n\t\t\t\t\tif ( hintName.startsWith( HINT_NATIVE_LOCK_MODE ) ) {\n\t\t\t\t\t\t// out-of-date support for specifying alias-specific lockmodes\n\t\t\t\t\t\tapplyLockModeHint( HINT_NATIVE_LOCK_MODE, value );\n\t\t\t\t\t\treturn true;\n\t\t\t\t\t}\n\t\t\t\t\treturn false;\n\t\t\t}\n\t\t}\n\t\tcatch ( ClassCastException e ) {\n\t\t\tthrow new IllegalArgumentException( \"Incorrect value for query hint: \" + hintName, e );\n\t\t}\n\t}\n\n\tprotected void applyQueryPlanCachingHint(String hintName, Object value) {\n\t\tqueryOptions.setQueryPlanCachingEnabled( getBoolean( value ) );\n\t}\n\n\tprotected void applyReadOnlyHint(String hintName, Object value) {\n\t\tqueryOptions.setReadOnly( getBoolean( value ) );\n\t}\n\n\tprotected void applyFetchSizeHint(String hintName, Object value) {\n\t\tqueryOptions.setFetchSize( getInteger( value ) );\n\t}\n\n\tprotected void applyResultCachingHint(String hintName, Object value) {\n\t\tqueryOptions.setResultCachingEnabled( getBoolean( value ) );\n\t}","sourceCodeStart":588,"sourceCodeEnd":624,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java#L588-L624","documentation":"Thrown by AbstractCommonQueryContract.applyHint when a recognized Hibernate query hint is given a value of the wrong Java type. The switch that dispatches hints (e.g. 'org.hibernate.cacheRegion' and 'org.hibernate.fetchProfile' cast value to String, boolean/integer hints convert via getBoolean/getInteger) throws ClassCastException on a bad type, which is caught at hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java:605 and rethrown as IllegalArgumentException with this message. The hint name is echoed but not the expected type, so you must check the hint's contract in org.hibernate.jpa.HibernateHints (or LegacySpecHints/SpecHints) to see what type it wants.","triggerScenarios":"Calling query.setHint(\"org.hibernate.cacheRegion\", someInteger) or setHint(\"org.hibernate.fetchProfile\", Boolean.TRUE) — both handlers do (String) value. Passing a String where a Boolean/Integer-convertible value is expected for hints handled by getBoolean/getInteger can also surface as CCE only when conversion itself casts. Alias-specific lock hints like \"org.hibernate.lockMode.someAlias\" reaching applyLockModeHint with an unsupported object type instead goes to error 2364, not this one.","commonSituations":"Hints loaded from a properties/YAML file or framework layer (Spring Data @QueryHints, custom interceptors) where values arrive as strings or boxed numbers and are forwarded without conversion; copy-pasting hint code between native, HQL and procedure queries; upgrading Hibernate across 5.x→6.x→7.x where deprecated javax.* hint keys were re-routed to new handlers with stricter value types.","solutions":["Check the expected value type in the org.hibernate.jpa.HibernateHints javadoc for the exact hint key and pass that type (String for cacheRegion/fetchProfile, Boolean or String boolean for read-only/cacheable, Integer for fetchSize/timeout)","Use the Hint constants (HibernateHints.HINT_*, SpecHints.HINT_SPEC_*) instead of hand-typed strings so the key maps to a documented contract","If the value comes from configuration, convert it explicitly before setHint (e.g. String.valueOf(...), Boolean.parseBoolean(...))","Wrap setHint calls that take dynamic values in try/catch IllegalArgumentException and log the hint name and value class for a clear failure message"],"exampleFix":"// before\nMap<String, Object> hints = config.getHints();\nfor ( var e : hints.entrySet() ) query.setHint( e.getKey(), e.getValue() ); // ClassCastException -> Incorrect value for query hint: org.hibernate.fetchProfile\n\n// after\nquery.setHint( HibernateHints.HINT_FETCH_PROFILE, \"order-with-items\" ); // String value\nquery.setHint( HibernateHints.HINT_READ_ONLY, Boolean.TRUE ); // boolean value","handlingStrategy":"validation","validationCode":"Object v = hintValue;\nboolean ok = switch ( hintKey ) {\n    case HibernateHints.HINT_FETCH_PROFILE,\n         HibernateHints.HINT_CACHE_REGION -> v instanceof String;\n    case HibernateHints.HINT_READ_ONLY,\n         HibernateHints.HINT_QUERY_PLAN_CACHEABLE -> v instanceof Boolean || v instanceof String;\n    case HibernateHints.HINT_FETCH_SIZE -> v instanceof Integer || v instanceof String;\n    default -> true;\n};\nif ( !ok ) throw new IllegalArgumentException( \"Wrong type for hint \" + hintKey + \": \" + v.getClass() );\nquery.setHint( hintKey, v );","typeGuard":"static boolean isValidHintValue(String key, Object v) {\n    return switch ( key ) {\n        case HibernateHints.HINT_CACHE_REGION, HibernateHints.HINT_FETCH_PROFILE -> v instanceof String;\n        case HibernateHints.HINT_FETCH_SIZE -> v instanceof Integer || v instanceof String;\n        case HibernateHints.HINT_READ_ONLY -> v instanceof Boolean || v instanceof String;\n        default -> true;\n    };\n}","tryCatchPattern":"try {\n    query.setHint( hintKey, value );\n} catch ( IllegalArgumentException e ) {\n    throw new IllegalStateException( \"Bad value for hint '\" + hintKey + \"': class=\" + (value == null ? \"null\" : value.getClass().getName()), e );\n}","preventionTips":["Keep a single typed hint-constants class mapping each key to its expected value type","Convert config-sourced hint values (String) to the documented type before setHint","Write a unit test that applies your full default hint map to one HQL and one native query so type regressions surface in CI"],"tags":["hibernate","query-hints","sethint","class-cast","illegalargument","orm"],"backgroundTag":"query-hint-invalid-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}