nginx fails to start: could not build the server_names_hash
could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32Short answer
nginx builds a hash table of all server names at start. The error comes in two forms. One long name needs a bigger server_names_hash_bucket_size, raised to the next power of two. Many names need a bigger server_names_hash_max_size first. Set both in the http block.
Fix it fast
1Find out which cause you have
Read which of the two messages you got, and count the server names in the config.
sudo nginx -t sudo nginx -T 2>/dev/null | grep -c "server_name"2Match what you see, then jump to its fix
What does the error look like?
could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32could not build the server_names_hash, you should increase either server_names_hash_max_size: 512 or server_names_hash_bucket_size: 32
Cause 1 of 2
One server name is longer than a bucket
1Check
The default bucket size is 32, 64 or another value, depending on the CPU cache line size. A name such as too.long.server.name.example.org does not fit into 32 and nginx stops.
sudo nginx -T 2>/dev/null | grep -E "server_name" | awk '{ for (i=2;i<=NF;i++) print length($i), $i }' | sort -rn | head -n 32Fix
Raise the bucket size to the next power of two in the http block.
http {
server_names_hash_bucket_size 64;
}3Verify
The configuration test should pass.
sudo nginx -tConfirmed by nginx.org
Cause 2 of 2
There are many server names
1Check
Large setups with a lot of virtual hosts hit the table size limit, 512 by default for the max size.
sudo nginx -T 2>/dev/null | grep -c "server_name"2Fix
Set server_names_hash_max_size to a number close to the number of names first. Increase the bucket size only if that does not help, or if the start becomes too slow.
http {
server_names_hash_max_size 1024;
}3Verify
Run the test, then reload.
sudo nginx -t && sudo nginx -s reloadConfirmed by nginx.org
How do I stop it coming back?
- Put both directives in the http block in nginx.conf so every added site starts with room to grow.
- Run nginx -t after adding a long host name or a batch of new sites.
- Change only one of the two values at a time and test, as the docs advise max_size first for large lists.
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
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 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
Docker php image has no php.ini and my edits do not stay
A setting changed in php.ini inside the container is gone after the container is recreated
The official php image ships php.ini-development and php.ini-production but no active php.ini.
2 causes, each with a fix