Maaz Zindani

Loading the index…

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

nginx warns that it could not build an optimal types_hash

Errorcould 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

Short answer

nginx builds a lookup table from mime.types and warns when the table does not fit its limits. It is a warning, not a crash. Raise types_hash_max_size in the http block first (the default is 1024). If the warning stays, raise types_hash_bucket_size (default 64), then run nginx -t again.

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

Fix it fast

  1. 1Find out which cause you have

    Run the config test and read the warning. The numbers in it are the values nginx is using right now.

    sudo nginx -t
  2. 2Match what you see, then jump to its fix

    1. 1the warning appears and the max_size number in it is still the default, 1024types_hash_max_size is too small for the number of typesFix
    2. 2the same warning after types_hash_max_size was raisedThe bucket size is too small, so raising max size alone does not helpFix

What does the error look like?

  • 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

Cause 1 of 2

types_hash_max_size is too small for the number of types

1Check

The table is sized from every type nginx loads, which comes from mime.types plus any types block you wrote. Check whether the directive is already set anywhere.

sudo nginx -T 2>/dev/null | grep -n -E "types_hash|mime.types"

2Fix

nginx's own guidance is to raise the max size first. Set it in the http block and keep the bucket size as it is for now.

http {
    include       mime.types;
    types_hash_max_size 2048;
}

3Verify

The test passes with no warning line.

sudo nginx -t

Confirmed by nginx.org

Did this fix it?

Cause 2 of 2

The bucket size is too small, so raising max size alone does not help

1Check

Each bucket holds the entries whose hash values collide. When a bucket cannot hold them, nginx asks for a bigger bucket size. It rounds this value up to a multiple of the processor cache line size.

sudo nginx -T 2>/dev/null | grep -n "types_hash"

2Fix

Double the bucket size from the default 64 and keep the larger max size.

http {
    types_hash_max_size    2048;
    types_hash_bucket_size 128;
}

3Verify

Run the test again, then reload.

sudo nginx -t
sudo systemctl reload nginx

Confirmed by nginx.org

Did this fix it?

How do I stop it coming back?

  • Keep mime.types and any custom types blocks small; add only the types you serve.
  • Put the two directives in nginx.conf, not in a vhost, so one setting covers every site.
  • Run nginx -t after every config change and read the output, since this message is only a warning and is easy to miss.

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

Next step

Want this handled for good?

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