LogoفارسیFA

Caching and Troubleshooting NGINX with Reverse Proxy in cPanel & WHM

This article explains how caching works in NGINX with reverse proxy on cPanel & WHM servers. It covers cache storage, cache control headers, custom cache keys, using .htaccess for cache management, third‑party integration, and common troubleshooting issues such as proxy_headers_hash errors and restart failures.

NGINX cachingreverse proxy troubleshootingcPanel NGINX cache

~3 min read • Updated Feb 22, 2026

1. Overview


This document describes how caching works in NGINX® with reverse proxy and provides troubleshooting guidance for common issues.



2. Caching in NGINX with Reverse Proxy


NGINX reverse proxies to Apache and caches all requests by default. Cache data is stored per user in the following directory, where type represents the cache type and username represents the account:

/var/cache/ea-nginx/proxy/username

NGINX uses the proxy cache type for the proxy_pass directive. Cache directories use 700 permissions and are restricted to nobody and root.


Your application must send proper cache-control headers for dynamic content. Without them, users may receive cached responses that do not apply to their session.


To fix this issue, you can:

  • Disable caching for the user in WHM’s NGINX Manager.
  • Modify your application to send correct cache-control headers.


3. Custom Cache Keys


You can configure NGINX to generate separate caches for different conditions (e.g., mobile vs. desktop users). To do this, set the $CACHE_KEY_PREFIX variable in:

/etc/nginx/conf.d/includes-optional/set-CACHE_KEY_PREFIX.conf

This file includes a commented example for mobile caching.


For more details, refer to the NGINX Proxy documentation.



4. Managing Caching with .htaccess


You can use .htaccess files to manage caching behavior. This is useful when your application does not set proper headers.


Example for disabling caching on sensitive paths:

# Application sends private data without proper headers.

    
        Header set Pragma "no-cache"
        Header set Cache-Control "max-age=0, no-cache, no-store, must-revalidate"
        Header set Expires "Thu, 1 Jan 1970 00:00:00 GMT"

Important: If your application does not send proper headers for sensitive data, it is a security risk.


To enable caching for common static files:


Header set Cache-Control "max-age=3600, public"


5. Third‑Party Integration


Third‑party tools can detect NGINX caching status using the following logic:

  • If /etc/nginx/ea-nginx/cache.json does not exist → NGINX is not installed.
  • If enabled exists in:

User-level file:

/var/cpanel/userdata/user/nginx-cache.json

Global file:

/etc/nginx/ea-nginx/cache.json

If neither file contains enabled, caching is enabled by default.



6. Troubleshooting NGINX


6.1 “Could not build proxy_headers hash” Error


You may see an error like:

nginx: [emerg] could not build proxy_headers_hash, you should increase proxy_headers_hash_bucket_size

This occurs when a proxy_set_header directive uses a very long header name.


Fix: Add the following directive immediately before the long header:

proxy_headers_hash_bucket_size number;


6.2 NGINX Will Not Restart


If you manually started NGINX using the nginx command, normal restart commands will fail.


Fix:

  1. Stop the service:
/usr/sbin/nginx -s stop

  1. Restart using one of the following:
/usr/local/cpanel/scripts/restartsrv_nginx start
systemctl start nginx.service
/etc/init.d/nginx start


Conclusion


NGINX caching with reverse proxy provides powerful performance benefits, but it requires proper application headers and careful configuration. With custom cache keys, .htaccess overrides, and clear troubleshooting steps, administrators can maintain a secure and efficient caching environment.


Written & researched by Dr. Shahin Siami

Next Article