How to solve Nginx error: could not build server_names_hash, you should increase server_names_hash_bucket_size 64

In the last week, I had to set up a load balancer in a VPS with Nginx to provide high availability in this setup. The idea behind it was quite simple: the load balancer should distribute incoming traffic across other servers to optimize resource use, improving response time and therefore increasing the availability. My client wanted this load balancer running in a subdomain of his company domain.

The task shouldn't take that long (that's what I said), but when I received the subdomain name that they wanted, I suspected that something could go wrong; the domain ended up being something like this:

thisisthesubdomain-itskindalongisnt.mycompanydomain.com.co

The domain of the client was 58 characters long. I never worked with a domain that long to be honest, so that was the reason why I ended up with this Nginx configuration error: could not build server_names_hash, you should increase server_names_hash_bucket_size.

Why does this happen

This problem is caused by the Nginx server_names_hash_bucket_size directive. This directive configures internally the size of the hash buckets that are used to store the server_name values defined in your server blocks (of each vhost). Nginx uses this hash table to efficiently look up the server names stored in your configuration (this includes long domain names and many server names in your setup). In most of the systems, the default value of this directive is 32 (bytes) for the size of the bucket.

So, when Nginx starts or is reloaded, it creates a hash table that matches the incoming host header (example.com) to the right server block. If you have plenty of server names or long domain names, the hash table needs more space than the default size.

How to solve it

To get over this error, you only need to increase the size of the hash bucket in your HTTP block, configure (or increase the value of) the directive with a higher value, such as 128 bytes (which was enough in my case). Modify the default nginx configuration file:

nano /etc/nginx/nginx.conf

Search for the HTTP block and increase the value of the directive (or add it if it doesn't exist):

http {
    server_names_hash_bucket_size 128;
    ...
}

Save the changes to the file, then test and reload Nginx:

sudo nginx -t

sudo systemctl reload nginx

And the issue should be gone now. It's important to keep in mind that:

• The default value is often 32 or 64 (depending on your system).

• It must be a power of two (e.g., 32, 64, 128, 256, 512).

• The server_names_hash_bucket_size directive controls the maximum length of the domain names that can be stored in one bucket.

• The longer or more domain names you use, the bigger this value needs to be.

• In the real world, the benefits of keeping the value of server_names_hash_bucket_size low are minimal, there's no real performance benefit from keeping this value small unless you're running thousands of server blocks on your machine. It's ok to set it to 128 or 256 by default unless you're doing super-fine memory tuning.

Happy coding ❤️!