{"record":{"id":"5ba58271fcf4444b","repo":"hibernate/hibernate-orm","slug":"unable-to-interpret-cachemode-in-named-query-hint","errorCode":null,"errorMessage":"Unable to interpret CacheMode in named query hint: \" + queryName","messagePattern":"Unable to interpret CacheMode in named query hint: \" \\+ queryName","errorType":"exception","errorClass":"AnnotationException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryHintDefinition.java","lineNumber":139,"sourceCode":"\tpublic Timeout getTimeoutRef() {\n\t\tfinal Integer timeoutSeconds = getTimeout();\n\t\treturn timeoutSeconds == null ? null : Timeout.seconds( timeoutSeconds );\n\t}\n\n\tpublic boolean getCacheability() {\n\t\treturn getBoolean( HibernateHints.HINT_CACHEABLE );\n\t}\n\n\t@Nullable\n\tpublic CacheMode getCacheMode() {\n\t\tfinal String value = getString( HibernateHints.HINT_CACHE_MODE );\n\t\ttry {\n\t\t\treturn value == null\n\t\t\t\t\t? null\n\t\t\t\t\t: CacheMode.interpretExternalSetting( value );\n\t\t}\n\t\tcatch (Exception e) {\n\t\t\tthrow new AnnotationException( \"Unable to interpret CacheMode in named query hint: \" + queryName, e );\n\t\t}\n\t}\n\n\t@Nullable\n\tpublic QueryFlushMode getFlushMode() {\n\t\tfinal String value = getString( HibernateHints.HINT_FLUSH_MODE );\n\t\ttry {\n\t\t\treturn value == null\n\t\t\t\t\t? null\n\t\t\t\t\t: FlushModeTypeHelper.queryFlushModeFromHint( value );\n\t\t}\n\t\tcatch (MappingException e) {\n\t\t\tthrow new AnnotationException( \"Unable to interpret FlushMode in named query hint: \" + queryName, e );\n\t\t}\n\t}\n\n\t@Nullable\n\tpublic LockMode getLockMode(String query) {","sourceCodeStart":121,"sourceCodeEnd":157,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/boot/model/internal/QueryHintDefinition.java#L121-L157","documentation":"QueryHintDefinition.getCacheMode reads the org.hibernate.cacheMode hint string and calls CacheMode.interpretExternalSetting, which only accepts the enum names NORMAL, IGNORE, GET, PUT, REFRESH (case-insensitive). An unrecognized value throws a MappingException that getCacheMode wraps in AnnotationException, naming the query. Validation happens at bootstrap while the named query definition is initialized.","triggerScenarios":"@QueryHint(name = \"org.hibernate.cacheMode\", value = \"read-write\") — a cache concurrency-strategy name rather than a CacheMode; also \"use_query_cache\", \"ALL\", or any made-up label. Fires when binding the named query that carries the hint.","commonSituations":"Confusing CacheMode (NORMAL/GET/PUT/REFRESH/IGNORE) with cache concurrency strategies (read-only/read-write/transactional); copying second-level-cache region config values into the cacheMode hint; values pasted from persistence.xml shared-cache-mode docs.","solutions":["Use one of the five CacheMode names: NORMAL, IGNORE, GET, PUT, REFRESH (e.g. \"GET\" to read from cache without putting).","If you meant to pick a collection/entity caching strategy, that belongs on @Cache(usage = ...) or region config, not the cacheMode hint.","Remove the hint if you only wanted default NORMAL behavior."],"exampleFix":"// before\n@QueryHint(name = \"org.hibernate.cacheMode\", value = \"read-write\")\n\n// after\n@QueryHint(name = \"org.hibernate.cacheMode\", value = \"GET\")","handlingStrategy":"validation","validationCode":"@Test void cacheModeHintUsesEnumName() {\n    Set<String> valid = Set.of(\"NORMAL\", \"IGNORE\", \"GET\", \"PUT\", \"REFRESH\");\n    for (QueryHint h : collectHints()) {\n        if (\"org.hibernate.cacheMode\".equals(h.name()))\n            assertTrue(valid.contains(h.value().toUpperCase(Locale.ROOT)),\n                \"cacheMode must be one of \" + valid + \", was: \" + h.value());\n    }\n}","typeGuard":"boolean isValidCacheModeHint(String v) {\n    return Arrays.stream(CacheMode.values()).anyMatch(m -> m.name().equalsIgnoreCase(v));\n}","tryCatchPattern":"try {\n    metadata = sources.buildMetadata();\n} catch (AnnotationException e) { // wraps CacheMode MappingException, names the query\n    failBuild(\"Unreadable cacheMode hint: \" + e.getMessage());\n}","preventionTips":["CacheMode is NORMAL/GET/PUT/REFRESH/IGNORE - concurrency strategies belong on @Cache(usage=...).","Copy hint examples only from the Hibernate version you run; hint vocabularies drift across versions."],"tags":["hibernate","orm","query-hints","cache-mode","named-query"],"backgroundTag":"query-hint-invalid-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}