Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

nginx warns it could not build an optimal variables_hash

Errornginx: [warn] could not build optimal variables_hash, you should increase either variables_hash_max_size: 1024 or variables_hash_bucket_size: 64

Short 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.

  • Applies to nginx 1.26
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 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 -t
  2. 2Match what you see, then jump to its fix

    1. 1The warning appears after adding many map, geo or set blocks, or custom variablesThe table holds more variables than variables_hash_max_size allowsFix
    2. 2The warning remains after the maximum was raisedA bucket is too small for variables whose hashes collideFix

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 -t

Confirmed by nginx.org

Did this fix it?

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_hash

2Fix

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 nginx

Confirmed by nginx.org

Did this fix it?

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 fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.