hibernate/hibernate-orm · error · IllegalArgumentException

Unknown EntityGraph hint name - `%s`. Expecting `%s` or `%s

Error message

Unknown EntityGraph hint name - `%s`.  Expecting `%s` or `%s` (or `%s` and `%s`).

What it means

GraphSemantic.fromHintName(String) translates an entity-graph query-hint name into FETCH or LOAD semantics. Only jakarta.persistence.fetchgraph/loadgraph and the legacy javax.persistence.fetchgraph/loadgraph names are accepted (per the switch in fromHintName); any other string throws IllegalArgumentException.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/graph/GraphSemantic.java:62

	/**
	 * The corresponding Jakarta Persistence hint name.
	 *
	 * @see org.hibernate.jpa.SpecHints#HINT_SPEC_FETCH_GRAPH
	 * @see org.hibernate.jpa.SpecHints#HINT_SPEC_LOAD_GRAPH
	 */
	public String getJakartaHintName() {
		return switch ( this ) {
			case FETCH -> HINT_SPEC_FETCH_GRAPH;
			case LOAD -> HINT_SPEC_LOAD_GRAPH;
		};
	}

	public static GraphSemantic fromHintName(String hintName) {
		return switch ( hintName ) {
			case HINT_SPEC_FETCH_GRAPH, HINT_JAVAEE_FETCH_GRAPH -> FETCH;
			case HINT_SPEC_LOAD_GRAPH, HINT_JAVAEE_LOAD_GRAPH -> LOAD;
			default -> throw new IllegalArgumentException(
					String.format(
							Locale.ROOT,
							"Unknown EntityGraph hint name - `%s`.  "
									+ "Expecting `%s` or `%s` (or `%s` and `%s`).",
							hintName,
							HINT_SPEC_FETCH_GRAPH,
							HINT_SPEC_LOAD_GRAPH,
							HINT_JAVAEE_FETCH_GRAPH,
							HINT_JAVAEE_LOAD_GRAPH
					)
			);
		};
	}
}

View on GitHub (pinned to fad1729dce)

Solutions

1. Use the canonical names: 'jakarta.persistence.fetchgraph' / 'jakarta.persistence.loadgraph'
2. Never hard-code the string — take it from GraphSemantic.FETCH.getJakartaHintName() / GraphSemantic.LOAD.getJakartaHintName()
3. If parsing user input, validate against the four accepted names before calling fromHintName, defaulting or rejecting cleanly
4. For Hibernate-native APIs pass the GraphSemantic enum value directly (e.g. EntityGraphs.setFetchGraph) instead of a hint string

Example fix

// before
GraphSemantic semantic = GraphSemantic.fromHintName("org.hibernate.fetchGraph"); // throws

// after
GraphSemantic semantic = GraphSemantic.fromHintName(GraphSemantic.FETCH.getJakartaHintName());
// or simply
EntityGraphs.setFetchGraph(query, graph);

private static final Set<String> GRAPH_HINT_NAMES = Set.of(
        "jakarta.persistence.fetchgraph", "jakarta.persistence.loadgraph",
        "javax.persistence.fetchgraph", "javax.persistence.loadgraph");

static Optional<GraphSemantic> parseGraphHint(String name) {
    return GRAPH_HINT_NAMES.contains(name)
            ? Optional.of(GraphSemantic.fromHintName(name))
            : Optional.empty();
}

When it happens

Trigger: Passing a wrong or non-standard hint string: 'org.hibernate.fetchGraph' (old native name), 'fetchgraph' (no prefix), wrong case ('fetchGraph'), or arbitrary user input when implementing custom hint parsing around GraphSemantic.fromHintName.

Common situations: javax→jakarta migrations with mixed catalogs; copying pre-JPA-3.1 Hibernate examples; building generic hint plumbing that forwards arbitrary user-supplied hint names to this parser.

Related errors

• Duplicate named entity graph '%s'
• The 'root' parameter of the @NamedEntityGraph should be pass
• The 'root' parameter of the @NamedEntityGraph annotation mus
• Unrecognized JPA persistence.xml XSD version : `{}`
• Unrecognized JPA orm.xml XSD version : `{}`

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