{"record":{"id":"dc9292f582611b34","repo":"hibernate/hibernate-orm","slug":"query-spaces-hint-was-specified-for-non-native-que","errorCode":null,"errorMessage":"Query spaces hint was specified for non-native query","messagePattern":"Query spaces hint was specified for non-native query","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java","lineNumber":757,"sourceCode":"\n\tprotected void applyLockTimeoutHint(String hintName, Object timeout) {\n\t\t//noinspection removal\n\t\tqueryOptions.getLockOptions().setTimeout( Timeouts.fromJpaHint( timeout ) );\n\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// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~","sourceCodeStart":739,"sourceCodeEnd":775,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java#L739-L775","documentation":"Thrown by the base AbstractCommonQueryContract.applySynchronizeSpacesHint (line 756), which unconditionally throws. The 'org.hibernate.query.native.spaces' hint tells Hibernate which tables a NATIVE query touches (for auto-invalidating the query cache and for followed-on synchronization); only NativeQueryImpl overrides this method to accept the value, so applying the hint to any non-native query contract (HQL/JPQL, Criteria, mutation queries, procedure calls using this base behavior) fails immediately.","triggerScenarios":"hqlQuery.setHint(\"org.hibernate.query.native.spaces\", \"order_table\") where hqlQuery came from session.createQuery(\"from Order\", Order.class). CriteriaQuery with the same hint. StoredProcedureQuery/procedure calls that inherit the base implementation.","commonSituations":"Migrating a native SQL query to HQL and keeping the spaces hint 'for cache invalidation'; code that applies a shared hint map to every query in a helper; older Hibernate versions where the key (formerly 'org.hibernate.query.spaces' era behavior) was silently ignored instead of throwing.","solutions":["Remove the hint from HQL/Criteria queries — Hibernate derives affected query spaces for non-native queries automatically","If you need manual space control (cache invalidation for tables touched by triggers etc.), keep the query native (session.createNativeQuery) or add the spaces on NativeQuery via addSynchronizedEntityClass/addSynchronizedQuerySpace","Make shared hint-application code skip the spaces hint unless the query is a NativeQuery"],"exampleFix":"// before\nQuery q = session.createQuery( \"from Order\", Order.class );\nq.setHint( HibernateHints.HINT_NATIVE_SPACES, \"order_table\" ); // throws: non-native query\n\n// after\nQuery q = session.createQuery( \"from Order\", Order.class );\n// no spaces hint needed: HQL knows its own spaces\n// or, if spaces must be manual:\nNativeQuery<?> nq = session.createNativeQuery( \"select * from order_table\" );\nnq.addSynchronizedQuerySpace( \"order_table\" );","handlingStrategy":"validation","validationCode":"Map<String, Object> hints = baseHints;\nif ( !( query instanceof org.hibernate.query.NativeQuery<?> ) ) {\n    hints = new HashMap<>( hints );\n    hints.remove( HibernateHints.HINT_NATIVE_SPACES );\n}\nhints.forEach( query::setHint );","typeGuard":"static boolean acceptsSpacesHint(jakarta.persistence.Query q) {\n    return q instanceof org.hibernate.query.NativeQuery<?>;\n}","tryCatchPattern":null,"preventionTips":["Tag provider-specific hints (spaces, callableFunction*) as native-only in your constants class","In shared hint appliers, branch on the query's concrete Hibernate interface","Rely on automatic space derivation for HQL/Criteria; document that manual spaces exist only for native SQL"],"tags":["hibernate","query-hints","native-query","query-spaces","cache-invalidation"],"backgroundTag":"query-hint-wrong-query-type","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}