Fix “could not build server_names_hash” in Nginx

Read the complete error before changing settings. An unusually long hostname can require a larger server_names_hash_bucket_size; a large collection of names may call for a larger server_names_hash_max_size. Both directives belong in the http context.

Choose the setting indicated by the error

The bucket default depends on the CPU cache line; the maximum-size default is 512. Avoid treating either as a per-domain memory quota. Hash construction also depends on name lengths and distribution.

For example, within the existing http block:

http {
    server_names_hash_bucket_size 128;
    server_names_hash_max_size 2048;

    include /etc/nginx/conf.d/*.conf;
    include /etc/nginx/sites-enabled/*;
}

This illustrates placement, not a full replacement nginx.conf. Keep the include paths used by your installation and set only the parameters needed for its error.

Test before reloading

sudo nginx -t && sudo systemctl reload nginx

Use the binary and startup options for the service you are changing. Check the service and error logs after reloading; a failed reload can leave old workers serving the previous configuration.

If increasing the maximum does not resolve the problem, or configuration startup becomes too slow, consider increasing the bucket size. The documentation recommends power-of-two steps for a bucket-size error; max_size does not have a general requirement to be a power of two or at least the exact number of names.

Review generated virtual hosts

This often appears after adding long tenant hostnames or generating many server blocks. Check for accidental duplication first. A wildcard can reduce configuration entries when all matching hosts genuinely share routing and access policy. A regex is not a free replacement: it changes matching behavior and is evaluated sequentially after exact and wildcard names.

If errors are collected with the Guance Nginx integration, compare records by instance and deployment time. Absence of a recent error should be combined with successful reload evidence and a request to the newly added hostname.

FAQ

Must I change both settings?

No. Start with the diagnostic's recommendation and retest. Avoid copying oversized values into every installation.

Can I use a bucket size of 1024?

It may be accepted, but a very large bucket can increase memory use. Raise it only as far as the configuration requires and evaluate startup behavior.

Why does the same error remain after editing?

Check that the directive is in http, that the edited file is included by the correct binary, and that the reload succeeded. nginx -T helps inspect current files but does not recover a previous in-memory configuration.

References: server-name optimization, hash table configuration.