nginx "could not build server_names_hash": Increase Bucket Size

nginx -t fails, or nginx refuses to start or reload, with one of these messages:

nginx: [emerg] could not build server_names_hash, you should increase server_names_hash_bucket_size: 32
nginx: [emerg] could not build the server_names_hash, you should increase either server_names_hash_max_size: 512 or server_names_hash_bucket_size: 64
nginx: configuration file /etc/nginx/nginx.conf test failed

nginx keeps every server_name in a hash table so it can find the right virtual host quickly. The table is built when the configuration loads. If one entry does not fit in a bucket, or the table cannot be made efficient with the allowed number of buckets, the build fails. Because [emerg] aborts the load, a reload leaves the old config running, while a restart leaves nginx down.

It usually appears right after you add a very long domain name or a lot of new vhosts.

The fix

Set a larger bucket size in the http context, in nginx.conf or a file included from it:

http {
    server_names_hash_bucket_size 128;
    # server_names_hash_max_size 1024;   # only if the message mentions it
    ...
}

Then test and reload:

sudo nginx -t && sudo systemctl reload nginx

Rules for choosing a value:

• The bucket size is a power of two, and the nginx documentation says the default is 32, 64 or 128 depending on the processor's cache line size. The error message prints the size currently in use, so go to the next step up: 32 becomes 64, 64 becomes 128, and so on.
• The first message variant (bucket size only) is fixed by raising server_names_hash_bucket_size. The second variant names both settings; raise server_names_hash_max_size first if you have hundreds of names, and the bucket size if you have long names.
• The directive goes in http, not inside a server block. Putting it elsewhere gives a "directive is not allowed here" error.

Larger values use more memory and make config load slightly slower, but for any normal number of sites the cost is negligible. Increase in steps rather than jumping to a huge number.

Why a long name can break it

Each name, plus some bookkeeping, has to fit in one bucket. A bucket of 32 bytes cannot hold a 40-character name. Typical triggers:

• Long subdomains such as very-long-customer-name.region.service.example.com.
• Many aliases listed in one server_name line.
• Wildcard entries combined with long literal names.
• Generated names from a hosting panel, preview environments or CI (pr-1234-my-feature-branch.preview.example.com).

Find the offending names

List every server_name entry in your config with its length, longest first:

grep -rhE '^\s*server_name' /etc/nginx/ | tr -d ';' | awk '{for(i=2;i<=NF;i++) print length($i), $i}' | sort -rn | head

Look for the longest names and for duplicates. Duplicate names across files produce a different warning (conflicting server name ... ignored), but cleaning duplicates still shrinks the table. If you have a mistakenly pasted full URL or a comment character in a server_name line, fix that too.

Large multi-tenant setups

If you host thousands of names, listing each in its own server block is the problem. Consider these designs instead:

1. A single server with a regular expression server_name ~^(?<tenant>.+)\.example\.com$; and routing by $tenant.
2. A wildcard certificate and wildcard server_name *.example.com, with the application deciding what to serve.
3. Generating a map from $host to a backend, so the number of server blocks stays small.

Regex server names are matched in order and are slower than hash lookups, so use them for the long tail, not for everything. Check your own load with a test before choosing.

How to verify

After a clean nginx -t, make sure every virtual host still answers. Loop over your hostnames and compare status codes:

for h in example.com www.example.com app.example.com; do
  curl -s -o /dev/null -w "$h %{http_code}\n" --resolve $h:443:127.0.0.1 https://$h/
done

Then check from outside with the HTTP Status Checker and confirm DNS for any new name with the DNS Checker. A monitor on each critical hostname through the Uptime Monitor helps you notice if a later reload fails and leaves a new site unrouted.

Next steps

• Check new hostnames with the DNS Checker.
• See Apache vs nginx troubleshooting for config habits.
• Read about nginx 404 for existing files if a new vhost serves the wrong content.
• Run a Website Health Check on the new site.

FAQ

Where does server_names_hash_bucket_size go?

In the http block of nginx.conf (or a file included there). It is not valid inside server or location.

What value should I use?

The next power of two above the size in the error message. If the message shows 32, try 64; if 64, try 128.

Does this affect performance?

Only marginally. A bigger bucket uses a little more memory at load time. Lookups remain fast.

Why did it break only after I added one site?

That one site probably has the longest name so far, or it pushed the table past what the old sizes could hold.

This page is general information written by our editorial team and updated when documentation changes. Servers and providers differ, so test changes safely first. See our editorial policy and disclaimer.