hibernate/hibernate-orm · error · IllegalArgumentException

The value of the hint '{hintName}' must be an instance of En

Error message

The value of the hint '{hintName}' must be an instance of EntityGraph, the string name of a named EntityGraph, or a string representation understood by GraphParser

What it means

Thrown by applyEntityGraphHint when a fetchgraph/loadgraph hint value is neither a RootGraphImplementor (Hibernate's EntityGraph) nor a String — i.e. the value has some other runtime type. Only EntityGraph instances (applied directly at line 649) and Strings (resolved as graph name or parsed graph string) are accepted; anything else hits the else branch at line 672.

Source

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

				applyGraph( getSession().getEntityGraph( string ), graphSemantic );
				// getEntityGraph throws an exception if not found.  but since we got here, it was found
				return;
			}
			catch (IllegalArgumentException ignore) {
				// fall through...
			}

			// try and parse it in the entity graph language
			try {
				applyGraph( parseGraph( string ), graphSemantic );
			}
			catch ( IllegalArgumentException e ) {
				throw new IllegalArgumentException( "The string value of the hint '" + hintName
													+ "' must be the name of a named EntityGraph, or a representation understood by GraphParser" );
			}
		}
		else {
			throw new IllegalArgumentException( "The value of the hint '" + hintName
												+ "' must be an instance of EntityGraph, the string name of a named EntityGraph, or a string representation understood by GraphParser" );
		}
	}

	protected void applyEnabledFetchProfileHint(String hintName, Object value) {
		queryOptions.enableFetchProfile( (String) value );
	}

	protected RootGraphImplementor<?> parseGraph(String graphString) {
		final int separatorPosition = graphString.indexOf( '(' );
		final int terminatorPosition = graphString.lastIndexOf( ')' );
		if ( separatorPosition < 0 || terminatorPosition < 0 ) {
			throw new IllegalArgumentException(
					String.format(
							ROOT,
							"Invalid entity-graph definition '%s'; expected form '${EntityName}( ${property1} ... )'",
							graphString
					)

View on GitHub (pinned to fad1729dce)

Solutions

1. Pass an EntityGraph obtained from the same EntityManager/SessionFactory: em.getEntityGraph(name) or em.createEntityGraph(Order.class) then build and pass it
2. Pass the String name of a registered @NamedEntityGraph
3. Guard nulls before calling setHint so an unset graph never reaches Hibernate
4. If you wrote setHint(HINT_FETCHGRAPH, someClass), replace it with a proper graph: em.createEntityGraph(someClass)

Example fix

// before
query.setHint( QueryHints.HINT_FETCHGRAPH, Order.class ); // Class is not EntityGraph nor String

// after
EntityGraph<Order> graph = em.createEntityGraph( Order.class );
graph.addAttributeNodes( "items" );
query.setHint( QueryHints.HINT_FETCHGRAPH, graph );

if ( !( value instanceof EntityGraph<?> ) && !( value instanceof String ) || value == null ) {
    throw new IllegalArgumentException( "Graph hint needs an EntityGraph or its name, got: " + (value == null ? "null" : value.getClass() ) );
}
query.setHint( QueryHints.HINT_FETCHGRAPH, value );

static boolean isGraphHintValue(Object v) {
    return v instanceof EntityGraph<?> || v instanceof String;
}

When it happens

Trigger: query.setHint("jakarta.persistence.loadgraph", Order.class) — passing the entity class instead of a graph. Passing an Integer/Boolean (wrong config key), a java.util.Optional, a graph builder object, or null (null instanceof RootGraphImplementor/String are both false, so a null value also lands here). Passing an EntityGraph implementation from a different JPA provider than the one backing the session.

Common situations: Confusion between 'graph name', 'graph object' and 'entity class' in code review-level mistakes; a null graph name coming from an unset optional config property being forwarded verbatim; mixing EclipseLink/Hiernate provider-specific graph APIs in the same codebase.

Related errors

• The string value of the hint '{hintName}' must be the name o
• jakarta.persistence.validation.group.{} is of unknown type:
• Given object was not an instance of {} [{}]
• Duplicate named entity graph '%s'
• Configuration property hibernate.jdbc.time_zone value [{}] i

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