hibernate/hibernate-orm · error · MappingException

Unknown Cache Mode: " + setting

Error message

Unknown Cache Mode: " + setting

What it means

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>').

Source

Thrown at hibernate-core/src/main/java/org/hibernate/CacheMode.java:209

	/**
	 * Interpret externalized form as an instance of this enumeration.
	 *
	 * @param setting The externalized form.
	 * @return The matching enum value.
	 *
	 * @throws MappingException Indicates the external form was not recognized as a valid enum value.
	 */
	public static CacheMode interpretExternalSetting(String setting) {
		if ( setting == null ) {
			return null;
		}

		try {
			return CacheMode.valueOf( setting.toUpperCase(Locale.ROOT) );
		}
		catch ( IllegalArgumentException e ) {
			throw new MappingException( "Unknown Cache Mode: " + setting );
		}
	}

	/**
	 * Interpret the given JPA modes as an instance of this enumeration.
	 */
	public static CacheMode fromJpaModes(CacheRetrieveMode retrieveMode, CacheStoreMode storeMode) {
		if ( retrieveMode == null && storeMode == null ) {
			return null;
		}

		if ( storeMode == null ) {
			storeMode = CacheStoreMode.BYPASS;
		}

		if ( retrieveMode == null ) {
			retrieveMode = CacheRetrieveMode.BYPASS;
		}

View on GitHub (pinned to fad1729dce)

Solutions

1. Use one of the five CacheMode names: NORMAL, IGNORE, GET, PUT, REFRESH (any case).
2. If you meant the second-level cache strategy, set 'hibernate.cache.default_cache_concurrency_strategy' (READ_WRITE, etc.) instead.
3. Validate the string against CacheMode.values() before applying it as a hint (e.g. from an external config source).
4. Remove the hint or property if the default NORMAL behavior is acceptable.

Example fix

// before - 'READ_WRITE' is not a CacheMode
@QueryHints(@QueryHint(name = "org.hibernate.cacheMode", value = "READ_WRITE"))

// after - valid CacheMode name
@QueryHints(@QueryHint(name = "org.hibernate.cacheMode", value = "REFRESH"))

static CacheMode parseCacheMode(String raw) {
    for (CacheMode m : CacheMode.values()) {
        if (m.name().equalsIgnoreCase(raw == null ? "" : raw.trim())) return m;
    }
    throw new IllegalArgumentException("Unknown cache mode: " + raw
            + " (expected NORMAL, IGNORE, GET, PUT, REFRESH)");
}
// parseCacheMode("READ_WRITE") -> fast, clear failure before Hibernate sees it

try {
    CacheMode mode = CacheMode.interpretExternalSetting(value);
} catch (MappingException e) {
    log.warn("Ignoring invalid cache mode {}: {}", value, e.getMessage());
    mode = CacheMode.NORMAL; // safe default for external input
}

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Unable to interpret CacheMode in named query hint: " + query
• Maximum capacity has to be at least twice the concurrencyLev
• The {storageEngine} storage engine is not supported
• Can't determine SQL statement type for statement: {sql}
• illegal identity column type

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