From abd92d41ec43ce3d4e14c61688c8dbc2159b49dc Mon Sep 17 00:00:00 2001
From: Gabriel Clima <gabriel.clima@gcore.com>
Date: Tue, 5 May 2026 05:53:30 +0000
Subject: [PATCH] Cache: warn when cache_min_uses exceeds the uses bitfield
 range.

The "uses" counter on ngx_http_cache_node_t is a 10-bit field, so once
"{proxy,fastcgi,uwsgi,scgi}_cache_min_uses" is configured at 1024 or
greater the threshold can never be reached and caching is silently
disabled.  Emit a config-time warning at the point where the directive
is set so the misconfiguration is visible without code reading.
---
 src/http/modules/ngx_http_fastcgi_module.c | 9 +++++++++
 src/http/modules/ngx_http_proxy_module.c   | 9 +++++++++
 src/http/modules/ngx_http_scgi_module.c    | 9 +++++++++
 src/http/modules/ngx_http_uwsgi_module.c   | 9 +++++++++
 4 files changed, 36 insertions(+)

diff --git a/src/http/modules/ngx_http_fastcgi_module.c b/src/http/modules/ngx_http_fastcgi_module.c
index f7f0696a8..5e3718fb3 100644
--- a/src/http/modules/ngx_http_fastcgi_module.c
+++ b/src/http/modules/ngx_http_fastcgi_module.c
@@ -3166,6 +3166,15 @@ ngx_http_fastcgi_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
         return NGX_CONF_ERROR;
     }
 
+    if (conf->upstream.cache_min_uses != NGX_CONF_UNSET_UINT
+        && conf->upstream.cache_min_uses > 1023)
+    {
+        ngx_conf_log_error(NGX_LOG_WARN, cf, 0,
+                           "\"fastcgi_cache_min_uses\" value %ui exceeds 1023 "
+                           "and effectively disables caching",
+                           conf->upstream.cache_min_uses);
+    }
+
     ngx_conf_merge_uint_value(conf->upstream.cache_min_uses,
                               prev->upstream.cache_min_uses, 1);
 
diff --git a/src/http/modules/ngx_http_proxy_module.c b/src/http/modules/ngx_http_proxy_module.c
index 7897b3f4b..7472b5068 100644
--- a/src/http/modules/ngx_http_proxy_module.c
+++ b/src/http/modules/ngx_http_proxy_module.c
@@ -3849,6 +3849,15 @@ ngx_http_proxy_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
         return NGX_CONF_ERROR;
     }
 
+    if (conf->upstream.cache_min_uses != NGX_CONF_UNSET_UINT
+        && conf->upstream.cache_min_uses > 1023)
+    {
+        ngx_conf_log_error(NGX_LOG_WARN, cf, 0,
+                           "\"proxy_cache_min_uses\" value %ui exceeds 1023 "
+                           "and effectively disables caching",
+                           conf->upstream.cache_min_uses);
+    }
+
     ngx_conf_merge_uint_value(conf->upstream.cache_min_uses,
                               prev->upstream.cache_min_uses, 1);
 
diff --git a/src/http/modules/ngx_http_scgi_module.c b/src/http/modules/ngx_http_scgi_module.c
index 91f5f7ccd..e1f5f051a 100644
--- a/src/http/modules/ngx_http_scgi_module.c
+++ b/src/http/modules/ngx_http_scgi_module.c
@@ -1579,6 +1579,15 @@ ngx_http_scgi_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
         return NGX_CONF_ERROR;
     }
 
+    if (conf->upstream.cache_min_uses != NGX_CONF_UNSET_UINT
+        && conf->upstream.cache_min_uses > 1023)
+    {
+        ngx_conf_log_error(NGX_LOG_WARN, cf, 0,
+                           "\"scgi_cache_min_uses\" value %ui exceeds 1023 "
+                           "and effectively disables caching",
+                           conf->upstream.cache_min_uses);
+    }
+
     ngx_conf_merge_uint_value(conf->upstream.cache_min_uses,
                               prev->upstream.cache_min_uses, 1);
 
diff --git a/src/http/modules/ngx_http_uwsgi_module.c b/src/http/modules/ngx_http_uwsgi_module.c
index 2f64d745d..ee26bcfc4 100644
--- a/src/http/modules/ngx_http_uwsgi_module.c
+++ b/src/http/modules/ngx_http_uwsgi_module.c
@@ -1839,6 +1839,15 @@ ngx_http_uwsgi_merge_loc_conf(ngx_conf_t *cf, void *parent, void *child)
         return NGX_CONF_ERROR;
     }
 
+    if (conf->upstream.cache_min_uses != NGX_CONF_UNSET_UINT
+        && conf->upstream.cache_min_uses > 1023)
+    {
+        ngx_conf_log_error(NGX_LOG_WARN, cf, 0,
+                           "\"uwsgi_cache_min_uses\" value %ui exceeds 1023 "
+                           "and effectively disables caching",
+                           conf->upstream.cache_min_uses);
+    }
+
     ngx_conf_merge_uint_value(conf->upstream.cache_min_uses,
                               prev->upstream.cache_min_uses, 1);