{"record":{"id":"98ce1b6d7c073602","repo":"hibernate/hibernate-orm","slug":"the-value-of-the-hint-hintname-must-be-an-inst","errorCode":null,"errorMessage":"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","messagePattern":"The value of the hint '(.+?)' must be an instance of EntityGraph, the string name of a named EntityGraph, or a string representation understood by GraphParser","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java","lineNumber":673,"sourceCode":"\t\t\t\tapplyGraph( getSession().getEntityGraph( string ), graphSemantic );\n\t\t\t\t// getEntityGraph throws an exception if not found.  but since we got here, it was found\n\t\t\t\treturn;\n\t\t\t}\n\t\t\tcatch (IllegalArgumentException ignore) {\n\t\t\t\t// fall through...\n\t\t\t}\n\n\t\t\t// try and parse it in the entity graph language\n\t\t\ttry {\n\t\t\t\tapplyGraph( parseGraph( string ), graphSemantic );\n\t\t\t}\n\t\t\tcatch ( IllegalArgumentException e ) {\n\t\t\t\tthrow new IllegalArgumentException( \"The string value of the hint '\" + hintName\n\t\t\t\t\t\t\t\t\t\t\t\t\t+ \"' must be the name of a named EntityGraph, or a representation understood by GraphParser\" );\n\t\t\t}\n\t\t}\n\t\telse {\n\t\t\tthrow new IllegalArgumentException( \"The value of the hint '\" + hintName\n\t\t\t\t\t\t\t\t\t\t\t\t+ \"' must be an instance of EntityGraph, the string name of a named EntityGraph, or a string representation understood by GraphParser\" );\n\t\t}\n\t}\n\n\tprotected void applyEnabledFetchProfileHint(String hintName, Object value) {\n\t\tqueryOptions.enableFetchProfile( (String) value );\n\t}\n\n\tprotected RootGraphImplementor<?> parseGraph(String graphString) {\n\t\tfinal int separatorPosition = graphString.indexOf( '(' );\n\t\tfinal int terminatorPosition = graphString.lastIndexOf( ')' );\n\t\tif ( separatorPosition < 0 || terminatorPosition < 0 ) {\n\t\t\tthrow new IllegalArgumentException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\tROOT,\n\t\t\t\t\t\t\t\"Invalid entity-graph definition '%s'; expected form '${EntityName}( ${property1} ... )'\",\n\t\t\t\t\t\t\tgraphString\n\t\t\t\t\t)","sourceCodeStart":655,"sourceCodeEnd":691,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/query/internal/AbstractCommonQueryContract.java#L655-L691","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Pass an EntityGraph obtained from the same EntityManager/SessionFactory: em.getEntityGraph(name) or em.createEntityGraph(Order.class) then build and pass it","Pass the String name of a registered @NamedEntityGraph","Guard nulls before calling setHint so an unset graph never reaches Hibernate","If you wrote setHint(HINT_FETCHGRAPH, someClass), replace it with a proper graph: em.createEntityGraph(someClass)"],"exampleFix":"// before\nquery.setHint( QueryHints.HINT_FETCHGRAPH, Order.class ); // Class is not EntityGraph nor String\n\n// after\nEntityGraph<Order> graph = em.createEntityGraph( Order.class );\ngraph.addAttributeNodes( \"items\" );\nquery.setHint( QueryHints.HINT_FETCHGRAPH, graph );","handlingStrategy":"type-guard","validationCode":"if ( !( value instanceof EntityGraph<?> ) && !( value instanceof String ) || value == null ) {\n    throw new IllegalArgumentException( \"Graph hint needs an EntityGraph or its name, got: \" + (value == null ? \"null\" : value.getClass() ) );\n}\nquery.setHint( QueryHints.HINT_FETCHGRAPH, value );","typeGuard":"static boolean isGraphHintValue(Object v) {\n    return v instanceof EntityGraph<?> || v instanceof String;\n}","tryCatchPattern":null,"preventionTips":["Never forward null or config objects into fetchgraph/loadgraph hints","Centralize graph-hint application in one helper that type-checks before calling setHint","Pass graphs built with em.createEntityGraph so type correctness is compile-visible"],"tags":["hibernate","entity-graph","fetchgraph","sethint","type-mismatch"],"backgroundTag":"entity-graph-hint-invalid","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}