nginx warns it could not build an optimal variables_hash
nginx: [warn] could not build optimal variables_hash, you should increase either variables_hash_max_size: 1024 or variables_hash_bucket_size: 64Short answer
nginx stores variables in a hash table and warns when its size limits are too small for the configuration. Add variables_hash_max_size in the http block first, then variables_hash_bucket_size if the warning remains. The defaults are 1024 and 64. It is a warning, but fixing it keeps start-up and reloads clean.
Fix it fast
1Find out which cause you have
Run the config test. The warning prints with the current sizes, and it shows again after each change until it is gone.
sudo nginx -t2Match what you see, then jump to its fix
What does the error look like?
nginx: [warn] could not build optimal variables_hash, you should increase either variables_hash_max_size: 1024 or variables_hash_bucket_size: 64
Cause 1 of 2
The table holds more variables than variables_hash_max_size allows
1Check
nginx picks the smallest table that works and keeps adjusting until the table size exceeds the maximum. The default maximum is 1024. The hash guide says to increase the max size parameter first.
grep -R -c -E "^\s*(map|geo|set) " /etc/nginx/2Fix
Raise the maximum in the http block, for example to double the default.
http {
variables_hash_max_size 2048;
}3Verify
Test again; the warning is gone.
sudo nginx -tConfirmed by nginx.org
Cause 2 of 2
A bucket is too small for variables whose hashes collide
1Check
The bucket size limits how many keys with the same hash one bucket can hold. The default is 64, and nginx aligns it to a multiple of the processor cache line size, so use a value that suits that size, such as 128.
sudo nginx -T 2>/dev/null | grep variables_hash2Fix
Raise variables_hash_bucket_size, and change one value at a time so you can see which one cleared the warning.
http {
variables_hash_max_size 2048;
variables_hash_bucket_size 128;
}3Verify
Test, reload and watch the error log.
sudo nginx -t && sudo systemctl reload nginxConfirmed by nginx.org
How do I stop it coming back?
- Keep the variables_hash settings in one include file that every http block shares.
- Run nginx -t when you add a large map or geo file.
- Change hash sizes only when nginx asks for it; larger tables use more memory.
Sources
How was this page made?
I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.
Which stack is behind this page?
Projects of mine built on the same technologies:
Related fixes
Servers
nginx warns that it could not build an optimal types_hash
could not build optimal types_hash, you should increase either types_hash_max_size: 1024 or types_hash_bucket_size: 64; ignoring types_hash_bucket_size
nginx builds a lookup table from mime.types and warns when the table does not fit its limits.
2 causes, each with a fixServers
nginx fails to start: could not build the server_names_hash
could not build the server_names_hash, you should increase either server_names_hash_max_size: 512 or server_names_hash_bucket_size: 32
nginx builds a hash table of all server names at start.
2 causes, each with a fixServers
Angular routes return 404 from nginx when you refresh or open a link
The home page loads, but refreshing /some/route shows an nginx 404
Angular routes like /users/42 are not files, so nginx looks for them on disk and returns 404.
3 causes, each with a fixServers
Argo CD behind an nginx Ingress loops with too many redirects
307 Temporary Redirect on every request to the Argo CD host
The browser and Argo CD disagree about who handles TLS.
3 causes, each with a fixServers
A Let's Encrypt certificate did not renew with Certbot
Type: connection ... Timeout during connect (likely firewall problem)
Run sudo certbot renew --dry-run and read the Type and Detail lines.
6 causes, each with a fixServers
curl cannot connect to port 80 or 443 on a server running nginx
CURLE_COULDNT_CONNECT (7): Failed to connect() to host or proxy
Exit code 7 means the TCP connection itself failed, before any HTTP happened.
3 causes, each with a fix