{"record":{"id":"5e33297b14af4976","repo":"hibernate/hibernate-orm","slug":"unknown-entitygraph-hint-name-s-expecting","errorCode":null,"errorMessage":"Unknown EntityGraph hint name - `%s`.  Expecting `%s` or `%s` (or `%s` and `%s`).","messagePattern":"Unknown EntityGraph hint name - `(.+?)`\\.  Expecting `(.+?)` or `(.+?)` \\(or `(.+?)` and `(.+?)`\\)\\.","errorType":"exception","errorClass":"IllegalArgumentException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/graph/GraphSemantic.java","lineNumber":62,"sourceCode":"\n\t/**\n\t * The corresponding Jakarta Persistence hint name.\n\t *\n\t * @see org.hibernate.jpa.SpecHints#HINT_SPEC_FETCH_GRAPH\n\t * @see org.hibernate.jpa.SpecHints#HINT_SPEC_LOAD_GRAPH\n\t */\n\tpublic String getJakartaHintName() {\n\t\treturn switch ( this ) {\n\t\t\tcase FETCH -> HINT_SPEC_FETCH_GRAPH;\n\t\t\tcase LOAD -> HINT_SPEC_LOAD_GRAPH;\n\t\t};\n\t}\n\n\tpublic static GraphSemantic fromHintName(String hintName) {\n\t\treturn switch ( hintName ) {\n\t\t\tcase HINT_SPEC_FETCH_GRAPH, HINT_JAVAEE_FETCH_GRAPH -> FETCH;\n\t\t\tcase HINT_SPEC_LOAD_GRAPH, HINT_JAVAEE_LOAD_GRAPH -> LOAD;\n\t\t\tdefault -> throw new IllegalArgumentException(\n\t\t\t\t\tString.format(\n\t\t\t\t\t\t\tLocale.ROOT,\n\t\t\t\t\t\t\t\"Unknown EntityGraph hint name - `%s`.  \"\n\t\t\t\t\t\t\t\t\t+ \"Expecting `%s` or `%s` (or `%s` and `%s`).\",\n\t\t\t\t\t\t\thintName,\n\t\t\t\t\t\t\tHINT_SPEC_FETCH_GRAPH,\n\t\t\t\t\t\t\tHINT_SPEC_LOAD_GRAPH,\n\t\t\t\t\t\t\tHINT_JAVAEE_FETCH_GRAPH,\n\t\t\t\t\t\t\tHINT_JAVAEE_LOAD_GRAPH\n\t\t\t\t\t)\n\t\t\t);\n\t\t};\n\t}\n}\n","sourceCodeStart":44,"sourceCodeEnd":77,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/graph/GraphSemantic.java#L44-L77","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Use the canonical names: 'jakarta.persistence.fetchgraph' / 'jakarta.persistence.loadgraph'","Never hard-code the string — take it from GraphSemantic.FETCH.getJakartaHintName() / GraphSemantic.LOAD.getJakartaHintName()","If parsing user input, validate against the four accepted names before calling fromHintName, defaulting or rejecting cleanly","For Hibernate-native APIs pass the GraphSemantic enum value directly (e.g. EntityGraphs.setFetchGraph) instead of a hint string"],"exampleFix":"// before\nGraphSemantic semantic = GraphSemantic.fromHintName(\"org.hibernate.fetchGraph\"); // throws\n\n// after\nGraphSemantic semantic = GraphSemantic.fromHintName(GraphSemantic.FETCH.getJakartaHintName());\n// or simply\nEntityGraphs.setFetchGraph(query, graph);","handlingStrategy":"validation","validationCode":"private static final Set<String> GRAPH_HINT_NAMES = Set.of(\n        \"jakarta.persistence.fetchgraph\", \"jakarta.persistence.loadgraph\",\n        \"javax.persistence.fetchgraph\", \"javax.persistence.loadgraph\");\n\nstatic Optional<GraphSemantic> parseGraphHint(String name) {\n    return GRAPH_HINT_NAMES.contains(name)\n            ? Optional.of(GraphSemantic.fromHintName(name))\n            : Optional.empty();\n}","typeGuard":null,"tryCatchPattern":null,"preventionTips":["Source hint names from GraphSemantic#getJakartaHintName, never string literals","Validate user-provided hint names against the accepted set before parsing","Standardize on jakarta hint names after the Jakarta EE 9+ migration"],"tags":["hibernate","entity-graph","query-hint","jakarta-ee","validation"],"backgroundTag":"unknown-query-hint","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}