Caching New Added 26 October 2026

nginx: [emerg] "proxy_cache" zone "my_cache" is unknown

proxy_cache refers to a shared memory zone that only exists once a proxy_cache_path line declares it with keys_zone=, and nginx found no zone with that name. Usually the server block was copied from another machine without the proxy_cache_path line that lived in that machine's nginx.conf, or the file declaring it is never included. A typo in keys_zone gives the same message. If proxy_cache_path sits inside a server block, nginx fails earlier with "directive is not allowed here", because it only belongs at http level.

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.

Quick fix

# Is the zone declared anywhere nginx actually loads?
sudo nginx -T 2>/dev/null | grep -nE "proxy_cache_path|proxy_cache "

# Declare it at http level, outside any server block,
# for example in /etc/nginx/conf.d/cache.conf:
# proxy_cache_path /var/cache/nginx/my_cache levels=1:2 keys_zone=my_cache:10m
#                  max_size=1g inactive=60m use_temp_path=off;

# The name in proxy_cache must match keys_zone exactly
# location / {
#     proxy_cache my_cache;
#     proxy_pass  http://app;
# }

sudo mkdir -p /var/cache/nginx/my_cache
sudo nginx -t && sudo systemctl reload nginx

How 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 Age header against your intended TTL. An Age larger than max-age means 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-cache for 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 -sI
varnishlog
CDN edge logs
Cache-Control validators

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

nginx.org

Related Caching errors

See all 20 Caching errors →

Browse other categories

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.