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_sizeShort 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.
Fix it fast
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 -t2Match what you see, then jump to its fix
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 -tConfirmed by nginx.org
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 nginxConfirmed by nginx.org
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
Servers
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
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 fixServers
Django returns a 500 behind Gunicorn and the traceback is nowhere
The traceback shows locally with runserver but not under Gunicorn
With DEBUG set to False, Django's default logging does not print errors to the console.
2 causes, each with a fixServers
Your website on a Google Compute Engine VM times out on port 80
The site works with curl on the VM but not from outside
A timeout, as opposed to a refusal, usually means a firewall dropped the packets.
3 causes, each with a fixServers
Gunicorn rejects a request with "Error parsing headers: limit request headers fields size"
Error parsing headers: 'limit request headers fields'
Gunicorn caps the size of one header field at 8190 bytes and the number of headers at 100 by default.
2 causes, each with a fix