Cache bypass conditions in Nginx - Commands & Configuration

Introduction

Sometimes you want your web server to skip using cached content and get fresh data instead. Cache bypass conditions let you tell the server when to ignore the cache and fetch new content.

When you want to show updated content after a user logs in without waiting for cache expiration

When certain cookies indicate personalized content that should not be cached

When a specific URL parameter means the content must be fresh

When you want to bypass cache for POST requests that change data

When debugging and you want to see live changes without cache interference

Config File - nginx.conf

nginx.conf

http {
    proxy_cache_path /tmp/nginx_cache levels=1:2 keys_zone=my_cache:10m max_size=100m inactive=60m use_temp_path=off;

    server {
        listen 80;

        location / {
            proxy_cache my_cache;
            proxy_pass http://backend_server;

            # Bypass cache if cookie "nocache" is set
            proxy_cache_bypass $cookie_nocache;

            # Bypass cache if URL has ?nocache=1
            set $bypass 0;
            if ($arg_nocache = 1) {
                set $bypass 1;
            }

            # Bypass cache if $bypass is 1
            proxy_cache_bypass $bypass;

            # Bypass cache for POST requests
            proxy_cache_bypass $request_method;
            proxy_cache_methods GET HEAD;
        }
    }
}

This configuration sets up a cache named my_cache stored in /tmp/nginx_cache. Inside the server block, the proxy_cache_bypass directives tell Nginx when to skip the cache:

• If the cookie named nocache exists, cache is bypassed.
• If the URL has the query parameter nocache=1, cache is bypassed.
• Cache is bypassed for POST requests because they usually change data.

The proxy_cache_methods limits caching to GET and HEAD requests only.

Commands

Check the Nginx configuration file for syntax errors before reloading.

Terminal

nginx -t

Expected Output

nginx: the configuration file /etc/nginx/nginx.conf syntax is ok

nginx: configuration file /etc/nginx/nginx.conf test is successful

Reload Nginx to apply the new cache bypass configuration without stopping the server.

Terminal

systemctl reload nginx

Expected Output

No output (command runs silently)

Send a simple GET request to check if the response is served from cache or bypassed.

Terminal

curl -I http://localhost/

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Thu, 01 Jun 2023 12:00:00 GMT

Content-Type: text/html

X-Cache-Status: MISS

Send a GET request with the nocache parameter to test cache bypass.

Terminal

curl -I http://localhost/?nocache=1

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Thu, 01 Jun 2023 12:00:01 GMT

Content-Type: text/html

X-Cache-Status: BYPASS

Send a POST request to verify that cache is bypassed for methods that change data.

Terminal

curl -I -X POST http://localhost/

Expected Output

HTTP/1.1 200 OK

Server: nginx

Date: Thu, 01 Jun 2023 12:00:02 GMT

Content-Type: text/html

X-Cache-Status: BYPASS

Key Concept

If you remember nothing else from this pattern, remember: cache bypass conditions tell Nginx exactly when to skip cached content and fetch fresh data.

Common Mistakes

Not testing the configuration with 'nginx -t' before reloading

This can cause Nginx to fail reloading and disrupt your web service.

Always run 'nginx -t' to verify syntax before reloading Nginx.

Using 'proxy_cache_bypass' without setting proper variables for conditions

Nginx may not bypass cache as expected, serving stale content instead.

Use variables like $cookie_nocache or custom variables set by 'if' to control bypass precisely.

Caching POST requests by mistake

POST requests usually change data and should not be cached, or users see outdated results.

Limit caching to GET and HEAD methods using 'proxy_cache_methods' and bypass cache for POST.

Summary

Configure 'proxy_cache_bypass' with variables to control when cache is skipped.

Test Nginx configuration syntax with 'nginx -t' before reloading.

Use curl commands with different conditions to verify cache bypass works as expected.