mybatis/mybatis-3 · error · CacheException

Not allowed to update a NullCacheKey instance.

Error message

Not allowed to update a NullCacheKey instance.

What it means

Thrown by the deprecated NullCacheKey class (deprecated since 3.5.3 because it is unused by the framework) when update(Object) is called on it. The class still exists for backward compatibility so old custom code constructing NullCacheKey directly does not break at class-load time, but mutation remains forbidden: a null key must stay empty to remain equal to every other null key.

Source

Thrown at src/main/java/org/apache/ibatis/cache/NullCacheKey.java:33

 */
package org.apache.ibatis.cache;

/**
 * @author Clinton Begin
 *
 * @deprecated Since 3.5.3, This class never used and will be removed future version.
 */
@Deprecated
public final class NullCacheKey extends CacheKey {

  private static final long serialVersionUID = 3704229911977019465L;

  public NullCacheKey() {
  }

  @Override
  public void update(Object object) {
    throw new CacheException("Not allowed to update a NullCacheKey instance.");
  }

  @Override
  public void updateAll(Object[] objects) {
    throw new CacheException("Not allowed to update a NullCacheKey instance.");
  }
}

View on GitHub (pinned to 008069adb1)

Solutions

1. Replace new NullCacheKey() usages with the shared CacheKey.NULL_CACHE_KEY constant and never call update on it
2. Delete the direct instantiation entirely — the framework supplies the sentinel where needed
3. If you truly need a mutable empty key, use new CacheKey() instead

Example fix

// before
CacheKey key = new NullCacheKey();
key.update(param);

// after
CacheKey key = new CacheKey();
key.update(param);

if (key instanceof NullCacheKey) throw new IllegalStateException("attempt to mutate NullCacheKey");

@Deprecated static boolean isNullKey(CacheKey k) { return k instanceof org.apache.ibatis.cache.NullCacheKey || k == CacheKey.NULL_CACHE_KEY; }

When it happens

Trigger: Legacy user code that does new NullCacheKey().update(x) — e.g. old custom cache decorators, executors, or tutorials targeting mybatis < 3.5.3 that instantiate NullCacheKey instead of using CacheKey.NULL_CACHE_KEY.

Common situations: Codebases built against very old mybatis (pre-3.4) where NullCacheKey was constructed directly; copy-pasted custom cache implementations from old blog posts; upgrading mybatis without revisiting custom cache plumbing.

Related errors

• Not allowed to update a null cache key instance.
• cache-ref element requires a namespace attribute.
• No cache for namespace '{namespace}' could be found.
• Cache-ref not yet resolved
• Should be specified either value() or name() attribute in th

AI-assisted analysis of mybatis/mybatis-3@008069adb1 (2026-08-14). Data as JSON: /api/errors/848735b4a8867e4d. Report an issue: GitHub.