Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Servers, nginx and Docker

nginx fails to start: could not build the server_names_hash

Errorcould not build the server_names_hash, you should increase server_names_hash_bucket_size: 32

Short answer

nginx builds a hash table of all server names at start. The error comes in two forms. One long name needs a bigger server_names_hash_bucket_size, raised to the next power of two. Many names need a bigger server_names_hash_max_size first. Set both in the http block.

  • Applies to nginx 1.26, nginx 1.28
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Read which of the two messages you got, and count the server names in the config.

    sudo nginx -t
    sudo nginx -T 2>/dev/null | grep -c "server_name"
  2. 2Match what you see, then jump to its fix

    1. 1The message mentions only server_names_hash_bucket_sizeOne server name is longer than a bucketFix
    2. 2The message says: increase either server_names_hash_max_size or server_names_hash_bucket_sizeThere are many server namesFix

What does the error look like?

  • could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32
  • could not build the server_names_hash, you should increase either server_names_hash_max_size: 512 or server_names_hash_bucket_size: 32

Cause 1 of 2

One server name is longer than a bucket

1Check

The default bucket size is 32, 64 or another value, depending on the CPU cache line size. A name such as too.long.server.name.example.org does not fit into 32 and nginx stops.

sudo nginx -T 2>/dev/null | grep -E "server_name" | awk '{ for (i=2;i<=NF;i++) print length($i), $i }' | sort -rn | head -n 3

2Fix

Raise the bucket size to the next power of two in the http block.

http {
    server_names_hash_bucket_size 64;
}

3Verify

The configuration test should pass.

sudo nginx -t

Confirmed by nginx.org

Did this fix it?

Cause 2 of 2

There are many server names

1Check

Large setups with a lot of virtual hosts hit the table size limit, 512 by default for the max size.

sudo nginx -T 2>/dev/null | grep -c "server_name"

2Fix

Set server_names_hash_max_size to a number close to the number of names first. Increase the bucket size only if that does not help, or if the start becomes too slow.

http {
    server_names_hash_max_size 1024;
}

3Verify

Run the test, then reload.

sudo nginx -t && sudo nginx -s reload

Confirmed by nginx.org

Did this fix it?

How do I stop it coming back?

  • Put both directives in the http block in nginx.conf so every added site starts with room to grow.
  • Run nginx -t after adding a long host name or a batch of new sites.
  • Change only one of the two values at a time and test, as the docs advise max_size first for large lists.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.