hibernate/hibernate-orm · error · IllegalArgumentException

Error applying query hint '%s': %s

Error message

Error applying query hint '%s': %s

What it means

Error "Error applying query hint '%s': %s" thrown in hibernate/hibernate-orm.

Source

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

	protected void putIfNotNull(Map<String, Object> hints, String hintName, Object hintValue) {
		if ( hintValue != null ) {
			hints.put( hintName, hintValue );
		}
	}

	@Override
	@Nonnull
	public CommonQueryContractImplementor setHint(@Nonnull String hintName, @Nullable Object value) {
		try {
			if ( !applyHint( hintName, value ) ) {
				QUERY_MESSAGE_LOGGER.ignoringUnrecognizedQueryHint( hintName );
			}
		}
		catch (IllegalArgumentException|IllegalStateException jpaExpected) {
			throw jpaExpected;
		}
		catch (Exception e) {
			throw new IllegalArgumentException(
					"Error applying query hint '%s': %s"
							.formatted( hintName, e.getMessage() ),
					e
			);
		}
		return this;
	}

	/**
	 * This method takes responsibility to recognize all known hints
	 * and collecting the values.
	 * <p>
	 * However, not all hints are valid for all types of queries which
	 * is beyond the understanding of this context.
	 * <p>
	 * Hints which are always relevant are handled by directly applying
	 * the corresponding option.  These include:<ul>
	 *     <li>{@linkplain QueryOptions#getQueryFlushMode() flush mode}

View on GitHub (pinned to fad1729dce)

Solutions

1. Applying the query hint failed. Verify the hint name is supported and its value has the expected type/format for that hint.

When it happens

Trigger: An invalid or inapplicable query hint is set: Error applying query hint '<value>': <value>

Common situations: Passing wrong-typed hint values, entity-graph hints that are neither named graphs nor parseable GraphParser strings, ProcedureCall-only hints on normal queries, or query-spaces hints on non-native queries.

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