What the message looks like
nginx: [emerg] could not build server_names_hash, you should increase server_names_hash_bucket_size: 64
nginx: configuration file /etc/nginx/nginx.conf test failedCommon causes
- One
server_nameis very long (for example a long subdomain), and a bucket is too small for it. - Many server names were added across
serverblocks, so the table needs a larger size. - The same name is listed in several places because a file is included twice, which inflates the table.
- A generated config (wildcard lists, many aliases per site) was added without raising the hash settings.
Check
- Run the configuration test
nginx -t - Current hash settings, if any
nginx -T 2>/dev/null | grep -nE 'server_names_hash' - The longest configured server names
nginx -T 2>/dev/null | grep -E '^\s*server_name' | tr -s ' ;' '\n' | awk 'length > 25' | sort -u - Is a file included twice?
nginx -T 2>/dev/null | grep -E '^# configuration file' | sort | uniq -d
Fix
- Add to the
httpblock in/etc/nginx/nginx.conf:server_names_hash_bucket_size 128;(a power of two; the message names the current value). - If the error stays or you have hundreds of names, also raise
server_names_hash_max_size, for example1024. - Remove duplicate includes so no name is defined twice.
- Test and apply:
nginx -t && systemctl reload nginx.
Typical scenario
You run a web server for many customer projects and a script creates a separate config file for each customer. When you add a domain with a very long subdomain, nginx -t fails: "could not build server_names_hash, you should increase server_names_hash_bucket_size: 64". The running nginx instance is untouched; only reloading fails. Read the current value in the message and double it in the http block.
FAQ
Which value should I use?
Double the value from the message and try again: 64 becomes 128, then 256 if needed. The bucket size must be a power of two.
Why does it appear after adding one more domain?
The table is sized when the configuration loads. One more or one longer name can be the one that no longer fits, even though the old setup worked.
Does the running nginx stay up when the configuration is faulty?
Yes. On reload nginx checks the new configuration first, and if that fails, the old workers keep running with the old configuration. A restart, however, would stop the service and then fail to start it. So test with nginx -t before every reload.
What does the default bucket size depend on?
It follows the processor's cache line size, so 32, 64 or 128 are common depending on hardware. That is why the error can occur on one server and not on another with the same configuration. The value must be a multiple of that size.
How do I find the names that exceed the limit?
nginx -T | grep server_name lists all names of the loaded configuration. Look for very long names and for files included twice. Long wildcard or regex names also take space. Then set the bucket value to fit instead of simply going high.