{"record":{"id":"930459c2ab5bdf28","repo":"hibernate/hibernate-orm","slug":"unknown-cache-mode-setting","errorCode":null,"errorMessage":"Unknown Cache Mode: \" + setting","messagePattern":"Unknown Cache Mode: \" \\+ setting","errorType":"exception","errorClass":"MappingException","httpStatus":null,"severity":"error","filePath":"hibernate-core/src/main/java/org/hibernate/CacheMode.java","lineNumber":209,"sourceCode":"\n\t/**\n\t * Interpret externalized form as an instance of this enumeration.\n\t *\n\t * @param setting The externalized form.\n\t * @return The matching enum value.\n\t *\n\t * @throws MappingException Indicates the external form was not recognized as a valid enum value.\n\t */\n\tpublic static CacheMode interpretExternalSetting(String setting) {\n\t\tif ( setting == null ) {\n\t\t\treturn null;\n\t\t}\n\n\t\ttry {\n\t\t\treturn CacheMode.valueOf( setting.toUpperCase(Locale.ROOT) );\n\t\t}\n\t\tcatch ( IllegalArgumentException e ) {\n\t\t\tthrow new MappingException( \"Unknown Cache Mode: \" + setting );\n\t\t}\n\t}\n\n\t/**\n\t * Interpret the given JPA modes as an instance of this enumeration.\n\t */\n\tpublic static CacheMode fromJpaModes(CacheRetrieveMode retrieveMode, CacheStoreMode storeMode) {\n\t\tif ( retrieveMode == null && storeMode == null ) {\n\t\t\treturn null;\n\t\t}\n\n\t\tif ( storeMode == null ) {\n\t\t\tstoreMode = CacheStoreMode.BYPASS;\n\t\t}\n\n\t\tif ( retrieveMode == null ) {\n\t\t\tretrieveMode = CacheRetrieveMode.BYPASS;\n\t\t}","sourceCodeStart":191,"sourceCodeEnd":227,"githubUrl":"https://github.com/hibernate/hibernate-orm/blob/fad1729dce015f908198d57a8d80274a30f905a5/hibernate-core/src/main/java/org/hibernate/CacheMode.java#L191-L227","documentation":"CacheMode.interpretExternalSetting converts a configuration/hint string into a CacheMode by upper-casing it and calling CacheMode.valueOf - so only the enum names NORMAL, IGNORE, GET, PUT and REFRESH are recognized (case-insensitive). Any other string causes valueOf to throw IllegalArgumentException, which is wrapped in MappingException('Unknown Cache Mode: <setting>').","triggerScenarios":"Setting the query hint 'org.hibernate.cacheMode' (HibernateHints.HINT_CACHE_MODE, e.g. in @QueryHints or named-query hints) to a string like 'READ_WRITE' or 'use-cache', or calling CacheMode.interpretExternalSetting(...) directly with a typo'd value. Note the QueryHintDefinition path wraps it further into an AnnotationException naming the query.","commonSituations":"Confusing CacheMode values with cache concurrency strategies (READ_WRITE, NONSTRICT_READ_WRITE, TRANSACTIONAL) and setting 'read-write' as the cache mode; typos like 'NORMAl2' or 'normal-mode'; copy-pasting hint values between properties.","solutions":["Use one of the five CacheMode names: NORMAL, IGNORE, GET, PUT, REFRESH (any case).","If you meant the second-level cache strategy, set 'hibernate.cache.default_cache_concurrency_strategy' (READ_WRITE, etc.) instead.","Validate the string against CacheMode.values() before applying it as a hint (e.g. from an external config source).","Remove the hint or property if the default NORMAL behavior is acceptable."],"exampleFix":"// before - 'READ_WRITE' is not a CacheMode\n@QueryHints(@QueryHint(name = \"org.hibernate.cacheMode\", value = \"READ_WRITE\"))\n\n// after - valid CacheMode name\n@QueryHints(@QueryHint(name = \"org.hibernate.cacheMode\", value = \"REFRESH\"))","handlingStrategy":"validation","validationCode":"static CacheMode parseCacheMode(String raw) {\n    for (CacheMode m : CacheMode.values()) {\n        if (m.name().equalsIgnoreCase(raw == null ? \"\" : raw.trim())) return m;\n    }\n    throw new IllegalArgumentException(\"Unknown cache mode: \" + raw\n            + \" (expected NORMAL, IGNORE, GET, PUT, REFRESH)\");\n}\n// parseCacheMode(\"READ_WRITE\") -> fast, clear failure before Hibernate sees it","typeGuard":null,"tryCatchPattern":"try {\n    CacheMode mode = CacheMode.interpretExternalSetting(value);\n} catch (MappingException e) {\n    log.warn(\"Ignoring invalid cache mode {}: {}\", value, e.getMessage());\n    mode = CacheMode.NORMAL; // safe default for external input\n}","preventionTips":["Validate externally supplied enum strings against the enum values before passing them in","Do not confuse CacheMode (NORMAL/IGNORE/GET/PUT/REFRESH) with cache concurrency strategies (READ_WRITE etc.)"],"tags":["cache","cache-mode","query-hints","configuration","mapping-exception"],"backgroundTag":"invalid-enum-config-value","analyzedSha":"fad1729dce015f908198d57a8d80274a30f905a5","analyzedAt":"2026-08-22T04:13:57.527Z","schemaVersion":2},"datasetVersion":"2026-08-22T09:17:25.309Z"}