hibernate/hibernate-orm · error · IllegalArgumentException

Query spaces hint was specified for non-native query

Error message

Query spaces hint was specified for non-native query

What it means

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.

Source

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

	protected void applyLockTimeoutHint(String hintName, Object timeout) {
		//noinspection removal
		queryOptions.getLockOptions().setTimeout( Timeouts.fromJpaHint( timeout ) );
	}

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


	// ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

View on GitHub (pinned to fad1729dce)

Solutions

1. Remove the hint from HQL/Criteria queries — Hibernate derives affected query spaces for non-native queries automatically
2. 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
3. Make shared hint-application code skip the spaces hint unless the query is a NativeQuery

Example fix

// before
Query q = session.createQuery( "from Order", Order.class );
q.setHint( HibernateHints.HINT_NATIVE_SPACES, "order_table" ); // throws: non-native query

// after
Query q = session.createQuery( "from Order", Order.class );
// no spaces hint needed: HQL knows its own spaces
// or, if spaces must be manual:
NativeQuery<?> nq = session.createNativeQuery( "select * from order_table" );
nq.addSynchronizedQuerySpace( "order_table" );

Map<String, Object> hints = baseHints;
if ( !( query instanceof org.hibernate.query.NativeQuery<?> ) ) {
    hints = new HashMap<>( hints );
    hints.remove( HibernateHints.HINT_NATIVE_SPACES );
}
hints.forEach( query::setHint );

static boolean acceptsSpacesHint(jakarta.persistence.Query q) {
    return q instanceof org.hibernate.query.NativeQuery<?>;
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Named native query definition object is null
• Named native query definition name is null: {}
• 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

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