hibernate/hibernate-orm · error · IllegalArgumentException

CacheMode cannot be null

Error message

CacheMode cannot be null

What it means

Session.setCacheMode declares @Nonnull and rejects null immediately with IllegalArgumentException. CacheMode is an enum-like contract (NORMAL, IGNORE, GET, PUT, REFRESH); there is no 'unset' value — the default is NORMAL — so null cannot be interpreted and is treated as a caller bug.

Source

Thrown at hibernate-core/src/main/java/org/hibernate/internal/AbstractSharedSessionContract.java:1632

	}

	@Override
	@Nonnull
	public final JdbcServices getJdbcServices() {
		return jdbcServices;
	}

	@Override
	@Nonnull
	public CacheMode getCacheMode() {
		return cacheMode;
	}

	@Override
	public void setCacheMode(@Nonnull CacheMode cacheMode) {
		//noinspection ConstantValue
		if ( cacheMode == null ) {
			throw new IllegalArgumentException( "CacheMode cannot be null" );
		}
		checkSessionReentrancy();
		this.cacheMode = cacheMode;
	}

	@Override
	public void setCriteriaCopyTreeEnabled(boolean jpaCriteriaCopyComplianceEnabled) {
		criteriaCopyTreeEnabled = jpaCriteriaCopyComplianceEnabled;
	}

	@Override
	public boolean isCriteriaCopyTreeEnabled() {
		return criteriaCopyTreeEnabled;
	}

	@Override
	public boolean isCriteriaPlanCacheEnabled() {
		return criteriaPlanCacheEnabled;

View on GitHub (pinned to fad1729dce)

Solutions

1. Default before setting: setCacheMode(cacheMode != null ? cacheMode : CacheMode.NORMAL).
2. Fix the property source so the value is present, and validate configuration keys at startup with a fail-fast check.
3. If the intent is 'cache normally', pass CacheMode.NORMAL explicitly.

Example fix

// before
CacheMode mode = props.containsKey("cache.mode") ? CacheMode.parse(props.get("cache.mode")) : null;
session.setCacheMode(mode); // IllegalArgumentException when key missing
// after
CacheMode mode = props.containsKey("cache.mode") ? CacheMode.parse(props.get("cache.mode")) : CacheMode.NORMAL;
session.setCacheMode(mode);

static CacheMode requireCacheMode(@Nullable CacheMode mode) {
    return mode != null ? mode : CacheMode.NORMAL;
}

// usage
session.setCacheMode(requireCacheMode(resolveFromConfig(props)));

When it happens

Trigger: session.setCacheMode(null), or setCacheMode(configValue) where the config lookup returned null: missing properties entry, Optional.empty() path, map.get() with a wrong key, or a nullable field from a properties class.

Common situations: Wiring CacheMode from a Spring property/environment entry that is not guaranteed to exist; copy-paste from code where CacheMode was optional; renaming a configuration key so the lookup silently returns null.

Related errors

• Result class is null
• null object passed to getCurrentLockMode()
• The OutputStream must not be null
• The InputStream must not be null
• The byte[] must not be null

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