Spring: java.lang.IllegalArgumentException: Cannot find cache named 'users'
A @Cacheable, @CachePut or @CacheEvict annotation names a cache that the CacheManager does not know and will not create. Spring Boot's default simple cache creates caches on demand, so everything works until a real provider arrives: Caffeine with spring.cache.cache-names set, or a JCache provider such as Ehcache 3, treats that list as fixed and rejects every other name. It often fails in only one profile, the one where a different cache type is configured.
Quick fix
Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.
# Which caches does the running app know? (needs actuator, with
# management.endpoints.web.exposure.include=caches)
curl -s localhost:8080/actuator/caches
# Every cache name the code uses
grep -rnE "@(Cacheable|CachePut|CacheEvict|CacheConfig)" src/main/java
# Which cache type does each profile configure?
grep -rn "spring.cache" src/main/resources/ 2>/dev/null
# Caffeine: list every name, or leave cache-names unset to create on demand
# spring.cache.type=caffeine
# spring.cache.cache-names=users,orders,products
# spring.cache.caffeine.spec=maximumSize=10000,expireAfterWrite=10m
# JCache / Ehcache 3: add <cache alias="users"> to ehcache.xmlHow to diagnose Caching errors
Cache problems are rarely reported as cache problems. They arrive as a traffic spike that takes down the origin (a stampede after a mass eviction), users seeing old content after a deploy, or an inexplicable 403 from the CDN. The unifying diagnostic is to look at the cache status header on a real response before theorising about anything else.
If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.
- Read the cache status header on a live request:
curl -sI https://example.com | grep -i -E 'cache|age|x-cache|cf-cache-status'. HIT, MISS and BYPASS each point at a different root cause. - Check the
Ageheader against your intended TTL. AnAgelarger thanmax-agemeans something is serving stale content deliberately (stale-while-revalidate), often the desired behaviour, occasionally the bug. - For stampedes, add request coalescing or a short randomised TTL jitter rather than a longer TTL. Identical expiry times across many keys are what create the thundering herd.
- Use content-hashed filenames for static assets and
no-cachefor HTML. Almost every "users see the old version" incident traces back to a long TTL on an HTML document. - For CDN 403s, distinguish a CDN-generated response from an origin one by checking whether CDN-specific headers are present. An origin 403 has a completely different fix.
Tools worth reaching for
curl -sIvarnishlogCDN edge logsCache-Control validators
Authoritative references
Primary documentation for this error, worth reading before applying any fix in production.
Related Caching errors
- Browser serving stale cache after deploymentUsers see old content after a deployment because their browsers cached the previous version…
- Cache stampede / thundering herdMultiple processes simultaneously attempt to rebuild the same expired cache entry…
- CDN: High cache miss ratioThe CDN is not caching responses effectively. Most requests are hitting the origin server…
- Cloudflare: cf-cache-status: DYNAMICDYNAMIC means Cloudflare never considered the response for caching, which is different from a…
- CloudFront: 403 Access DeniedCloudFront cannot access the S3 origin, usually because the bucket policy or Origin Access…
- CloudFront: 502 ERROR The request could not be satisfied (origin SSL failure)CloudFront connected to the origin over HTTPS but the TLS negotiation failed, so it returned…
- CloudFront: 504 ERROR The request could not be satisfied (origin timeout)CloudFront reached for your origin and either could not open a connection or got no response…
- Django: CacheKeyWarning: Cache key will cause errors if used with memcachedMemcached keys must be under 250 bytes and contain no spaces or control characters. Django…
Browse other categories
- HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
- JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
- Database 41Connections, deadlocks, constraints, replication and memory limits.
- AI 35Rate limits, context windows, GPU memory and model-serving failures.
- Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
- Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
- Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
- Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
- System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
- Cloud 25IAM permissions, quotas, service limits and credential failures.
- Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
- TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.
Something missing or wrong?
This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.