How to Bypass Nginx Cache for Development

In this tutorial, you'll learn about How to Bypass Nginx Cache for Development. We cover key concepts, practical examples, and best practices.

The Problem

During development, Nginx serves stale cached content even after you update the backend, because proxy_cache is enabled and the cache key has not expired.

Quick Fix

Send Cache-Busting Headers with curl

curl -H "Cache-Control: no-cache" http://localhost/endpoint
# < fresh response from backend >
curl -H "Pragma: no-cache" http://localhost/endpoint
# < fresh response >

The Cache-Control: no-cache header tells Nginx to forward the request to the backend and cache the new response. This works per-request without changing configuration.

Bypass Cache by Cookie or Header

sudo tee -a /etc/nginx/sites-available/myapp << 'EOF'
# In server or location block:
proxy_cache_bypass $http_x_bypass_cache;
proxy_no_cache $http_x_bypass_cache;
EOF
curl -H "X-Bypass-Cache: 1" http://localhost/endpoint
# < fresh response >

Configure proxy_cache_bypass and proxy_no_cache to skip the cache when a specific header (e.g., X-Bypass-Cache) is present. Use this header from your dev tools or browser extensions.

Add a Cache-Bypass Query Parameter

sudo tee -a /etc/nginx/nginx.conf << 'EOF'
map $arg_nocache $bypass_cache {
    1 1;
    default 0;
}
EOF
# Then in the location: proxy_cache_bypass $bypass_cache;
curl "http://localhost/endpoint?nocache=1"
# < fresh response >

Add a query parameter like ?nocache=1 to bypass the cache for debugging. The map block creates a variable that controls proxy_cache_bypass.

Purge the Cache Entirely (If Using proxy_cache_purge)

curl -X PURGE http://localhost/endpoint
# < HTML page saying "Successful purge" >
# Requires ngx_cache_purge module or proxy_cache_purge directive

Install the ngx_cache_purge module and add a proxy_cache_purge location to your Nginx config to allow purging specific cache keys via HTTP requests.

Configure Cache Keys for Granular Control

# In nginx.conf within the http block:
proxy_cache_key "\$scheme\$request_method\$host\$request_uri";
# This creates separate cache entries per URL, method, and protocol

Fine-tune the cache key to control when cached content is served. For example, excluding cookies from the cache key allows serving the same cached page to all users, while including the $http_accept_language header can serve language-specific variants.

Test Configuration Changes First

sudo nginx -t
# nginx: the configuration file syntax is ok
# nginx: configuration file test is successful
sudo systemctl reload nginx

Always run nginx -t before reloading the configuration. This validates syntax, checks file paths, and verifies that SSL certificates are accessible before applying changes.

Additional Troubleshooting

# Check the error message and stack trace for more context
echo "Review the full error output to identify the root cause"

If the above steps do not resolve the issue, examine the complete error message and stack trace. Often the key detail is in the middle of the traceback rather than the final line. Search for the error message in the project documentation or issue tracker for additional solutions.

Prevention

• Use proxy_cache_bypass with a dev header so developers can opt out of caching
• Set short cache TTLs (e.g., 1 minute) on development servers
• Use proxy_no_cache to skip caching for requests with specific cookies or user agents
• Layer a CDN in front of Nginx in production and disable CDN cache on staging