nginx: could not build server_names_hash – server_names_hash_bucket_size

Running nginx -t or nginx -s reload stops with [emerg] could not build the server_names_hash, you should increase server_names_hash_bucket_size: 32. Alternatively, nginx starts but logs [warn] could not build optimal server_names_hash, you should increase either server_names_hash_max_size: 512 or server_names_hash_bucket_size: 64.

This error means your configuration has exceeded a limit in nginx’s server name hashing logic. nginx builds this hash at configuration load time, not at request time. If the build fails, the configuration test fails. If the build succeeds but is suboptimal, nginx starts with degraded lookup performance. Both directives, server_names_hash_bucket_size and server_names_hash_max_size, are valid only inside the http context.

If the error appears during a reload, the previous configuration remains active. nginx does not stop serving traffic, but your change is not applied. Configuration drift can go undetected until someone notices the new server_name is not responding.

What this means

nginx uses hash tables to map incoming request Host headers to the correct server block. At startup or reload, it inserts exact and wildcard server_name values into hash tables. Regex server_name patterns are evaluated sequentially and are not hashed.

Two parameters bound this process:

• server_names_hash_bucket_size: the maximum bytes per bucket. It must accommodate the largest entry, which corresponds to your longest server_name string (including wildcard prefixes). The default is the CPU cache line size, commonly 32 or 64. This value must be a power of two.
• server_names_hash_max_size: the maximum number of buckets per hash table. The default is 512. It must accommodate the largest count of entries among the exact-name, wildcard-head, and wildcard-tail tables. Regex names do not count toward this limit.

If the largest entry exceeds the bucket size, the hash build fails and nginx emits [emerg]. If the number of names in a table approaches or exceeds max_size, the build may fail entirely or succeed with a [warn] about an optimal hash, indicating degraded lookup performance due to collisions.

flowchart TD
    A[nginx -t fails] --> B{Error type}
    B -->|bucket_size| C[Name too long]
    B -->|max_size| D[Too many names]
    B -->|optimal warning| D
    C --> E[Raise bucket_size to next power of two]
    D --> F[Raise max_size to near name count]
    F --> G{Still fails?}
    G -->|Yes| E
    G -->|No| H[Reload and verify]
    E --> H

Common causes

Quick checks

Run these before making changes. All are read-only and safe on a running instance.

# Capture the exact error text
nginx -t 2>&1

# Count server_name directives as a proxy for volume
grep -rh 'server_name' /etc/nginx/conf.d/ /etc/nginx/sites-enabled/ 2>/dev/null | wc -l

# Find the longest server_name value in bytes
grep -rhoE 'server_name[[:space:]]+[^;]+' /etc/nginx/conf.d/ /etc/nginx/sites-enabled/ 2>/dev/null | \
  sed 's/server_name[[:space:]]\+//' | tr ' ' '\n' | awk '{print length, $0}' | sort -rn | head -5

# Audit sites-enabled for stale symlinks (Debian/Ubuntu)
ls -la /etc/nginx/sites-enabled/

# Show existing hash directives in the http context
nginx -T 2>/dev/null | grep -E '^\s*(server_names_hash|types_hash|map_hash|variables_hash)'

# Check recent error log for hash-related emerg or warn entries
tail -100 /var/log/nginx/error.log | grep -E 'server_names_hash|could not build'

Use the output to decide which limit to raise. If the longest name is 48 bytes and bucket_size is 32, raise bucket_size to 64. If the name count is 700 and max_size is 512, raise max_size to 1024.

How to diagnose it

1. Read the exact error. Run nginx -t and note whether it names bucket_size, max_size, or both. The message determines which limit you hit.
2. Count unique server names. One server_name directive can hold multiple names. Count every individual exact and wildcard name. Regex names do not consume hash table space. Because nginx builds separate hash tables for exact names, wildcard names starting with *, and wildcard names ending with *, identify which category dominates your configuration. If the largest table count is near or above 512, raise max_size.
3. Measure the longest name. If you use long wildcard names (for example, *.very-long-subdomain.example.com), measure the character count. If it exceeds the current default bucket size (commonly 32 or 64), raise bucket_size.
4. Audit included configuration. On Debian and Ubuntu systems, check /etc/nginx/sites-enabled/ for symlinks that still load old server blocks. A dangling symlink causes a different nginx -t error, but a valid symlink to an obsolete config adds unwanted names to the hash.
5. Verify directive context. Both directives are valid only inside the http block. Placing them inside a server or location block causes a configuration test failure with a different error.
6. Distinguish related hash families. nginx maintains separate hash tables for server names, MIME types (types_hash), map variables (map_hash), and variables (variables_hash). An error about types_hash or map_hash is unrelated to server_names_hash and requires its own directive pair in the http context.

Fixes

Increase server_names_hash_max_size first

Raise server_names_hash_max_size before changing server_names_hash_bucket_size. Set it to a value near the count of the busiest server name hash table. If you are unsure of the current count, start with 1024 and adjust based on error log feedback after a successful reload. Add it inside the http block:

http {
    server_names_hash_max_size 1024;
    # ... rest of configuration
}

This is the preferred fix because it keeps buckets narrow and memory usage efficient.

Increase server_names_hash_bucket_size only when required

If the error specifically names bucket_size, or if startup time remains unacceptable after raising max_size, increase the bucket width to the next power of two:

http {
    server_names_hash_bucket_size 64;
    server_names_hash_max_size 1024;
}

Common settings are 64 or 128. Values of 256 and above are rarely needed unless you host exceptionally long DNS names. Do not set this arbitrarily high; each bucket is allocated to the full configured width, so doubling bucket_size doubles the hash table’s memory footprint even if most buckets are empty.

Clean up stale configuration (Debian/Ubuntu)

If nginx -t still fails after editing visible configs, a valid symlink in /etc/nginx/sites-enabled/ may be loading additional server_name entries from an old file. List the directory and remove symlinks to obsolete configurations before reloading:

ls -la /etc/nginx/sites-enabled/

Address suboptimal hash warnings

If nginx starts successfully but logs [warn] could not build optimal server_names_hash, the hash table is functional but collision-prone. Increase server_names_hash_max_size closer to your actual name count to eliminate the warning and restore lookup performance.

Handle analogous hash errors

If you see similar errors for other hash families, apply the same logic independently:

• types_hash_bucket_size and types_hash_max_size for MIME type tables
• map_hash_bucket_size and map_hash_max_size for map directives
• variables_hash_bucket_size and variables_hash_max_size for variables

Each pair belongs in the http context.

Prevention

• Size for growth. Set server_names_hash_max_size in your base http block to at least 2x your current unique exact and wildcard server name count so routine additions do not trigger warnings.
• Test before deploying. Run nginx -t in your CI pipeline before pushing configuration changes. A non-zero exit should block the deploy.
• Monitor for warnings. Treat [warn] could not build optimal messages as early indicators. They mean the hash is working but will degrade under further growth.
• Track name count. Add a check to your configuration management that counts server_name entries and alerts when approaching the configured max_size.
• Audit includes regularly. For distro-specific layouts with sites-enabled/, periodically verify that only intended configurations are active.
• Consolidate aliases. Remove redundant or unused server_name aliases to keep hash table counts low.

Metrics and signals to monitor

How Netdata helps

Netdata correlates spikes in nginx [emerg] and [warn] log rates with process events, letting you pinpoint which configuration change introduced the problem. It tracks worker process count to detect incomplete startups, and surfaces error log severity trends so you catch hash warnings before they escalate into failures.

Related guides

• How NGINX actually works in production: a mental model for operators
• nginx 413 Request Entity Too Large: client_max_body_size explained
• nginx 499 status code: why clients close connections before the response
• nginx 500 Internal Server Error: how to diagnose it
• nginx 502 Bad Gateway: causes and how to fix it
• nginx 503 Service Temporarily Unavailable: causes and fixes
• nginx 504 Gateway Time-out: causes and fixes
• NGINX active connections climbing: reading, writing, waiting explained
• NGINX backend cascade failure: when slow upstreams take down everything
• nginx: a client request body is buffered to a temporary file - what it means
• NGINX proxy cache hit rate is low: measuring and improving it
• nginx: configuration file test failed – finding the syntax error