Fix Nginx server_names_hash_bucket_size Errors on Your VPS

You add one more domain to your Nginx config, run nginx -t, and instead of "syntax is ok" you get a cryptic complaint about a hash bucket. Nothing was wrong a minute ago. Now Nginx won't reload, and if you restart it anyway, it won't even start. Here's what's happening and how to fix it properly on your SkyServer VPS.

The symptom

Depending on your Nginx version, you'll see one of these:

nginx: [emerg] could not build server_names_hash, you should increase server_names_hash_bucket_size: 32
nginx: configuration file /etc/nginx/nginx.conf test failed

Or the sibling message about the table size:

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

The key point: this is a configuration error, not a crash. A running Nginx keeps serving with its old config when a reload fails. But if you restart (or the server reboots) with this config in place, Nginx stays down and every site on the VPS goes with it.

What's actually going on

Nginx doesn't scan every server_name one by one for each request. It builds a hash table of all your server names when it loads the config, so lookups are fast. That table has two knobs:

• server_names_hash_max_size – how many slots the table has (default 512).
• server_names_hash_bucket_size – how many bytes each bucket can hold (default 32, 64 or 128 depending on your CPU's cache line size).

Each bucket has to fit at least one complete server name plus a bit of overhead. If you have a single very long hostname, it simply doesn't fit in a 32-byte bucket. Or if you have lots of names that happen to collide into the same bucket, they overflow it.

Typical triggers

The fix, step by step

1. Back up and find your http block

sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
sudo nano /etc/nginx/nginx.conf

These directives belong in the http { } block, not inside an individual server { } block. Putting them in a server block gives you a different error: "directive is not allowed here".

2. Raise the bucket size

The value must be a power of two. Go up one step at a time and re-test:

http {
    server_names_hash_bucket_size 64;
    # ...the rest of your config
}

If the error message says "bucket_size: 64" it means 64 wasn't enough either, so try 128. Rarely you'll need 256, and if you do, it's worth looking at whether you really need that hostname.

3. If you have lots of domains, raise the max size too

http {
    server_names_hash_max_size 2048;
    server_names_hash_bucket_size 128;
}

A rough rule: set max_size to a little above the total number of server names you have. A bigger table costs a few extra kilobytes of RAM, which is nothing on any VPS.

4. Test, then reload (not restart)

sudo nginx -t
sudo systemctl reload nginx

Always run nginx -t first. Only reload once it prints syntax is ok and test is successful.

5. Verify the sites respond

curl -I -H "Host: your-long-hostname.example.com" http://127.0.0.1/

That sends a request to the local Nginx with a specific Host header, so you can confirm the right server block answers without touching DNS.

If the error survives your change

• Duplicate setting: if you see "directive is duplicate", the same directive already exists elsewhere, often in /etc/nginx/conf.d/*.conf. Search for it with grep -rn server_names_hash /etc/nginx/ and keep just one copy.
• Edited the wrong file: on a control-panel or packaged build, the main config may be somewhere else. Run nginx -T | grep "configuration file" to see every file Nginx really loads.
• Typos in server_name: a stray character, like a missing semicolon or two names glued together, can create an absurdly long "name". Eyeball the line before blaming the hash.
• Warning about conflicting server name: that's a different thing. It means two blocks claim the same domain, and Nginx will just ignore one. Not related to hash size, but worth cleaning up.

Prevention

• Set a generous bucket size (64 or 128) when you first build the server if you plan to host many domains. It's free insurance.
• Keep one site per file under sites-available or conf.d, so you can disable a single new vhost quickly if a test fails.
• Make nginx -t && systemctl reload nginx your habit. The && means the reload only happens if the test passes.
• Prefer short, sensible hostnames for internal and staging sites. They're easier to type and kinder to the hash table.
• Take a VPS snapshot before big config rewrites, so you can roll back in minutes.

Rule of thumb: if the message mentions bucket_size, double it. If it mentions max_size as well, raise both.

Frequently Asked Questions

Will raising server_names_hash_bucket_size slow Nginx down?

Not in any way you'd notice. Larger buckets use slightly more memory and may take an extra cache line to read, but lookups remain very fast. It's the standard fix recommended for exactly this error.

Why does the value have to be a power of two?

Nginx aligns the buckets to the CPU cache line size, and it rounds the value up to the next multiple of that size anyway. Use 32, 64, 128 or 256 and you'll stay out of trouble.

Can I put these directives inside a server block?

No. They're only valid in the http context. Put them in nginx.conf or in a file under conf.d that's included from the http block.

My Nginx is down because of this. What's the fastest recovery?

Fix the setting as above, run sudo nginx -t, then sudo systemctl start nginx. If you can't spot the problem, temporarily disable the newest vhost file, start Nginx, and then work on the fix with the other sites already back online.

Do I see this error on cPanel shared hosting?

No. This is something you configure yourself on a VPS or dedicated server running Nginx. On shared cpanel" class="auto-link">cPanel hosting, we manage the web server settings for you.