WebServer New Added 8 September 2026

Nginx: could not build server_names_hash, increase the bucket size

Nginx sizes a hash table for server names at startup and one of your names is too long for the default bucket, which is tied to the CPU cache line. It stops the configuration from loading entirely, so it usually surfaces on reload after adding a long hostname.

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

Quick fix

# Raise it in the http block, powers of two
http {
    server_names_hash_bucket_size 128;
    server_names_hash_max_size 2048;   # for many names rather than long ones
}

# Always test before reloading, a broken config takes the reload with it
nginx -t && systemctl reload nginx

# Find the long names
grep -rh server_name /etc/nginx/ | tr ' ' '\n' | awk '{print length, $0}' \
  | sort -rn | head

# Wildcards are cheaper than a long list: *.api.example.com

How to diagnose WebServer errors

Web server errors are usually about permissions, binding, or configuration that was never loaded. A common trap: the server runs as an unprivileged user (www-data, nginx), so it needs execute permission on every directory in the path to a file, not just read permission on the file itself. Another: editing a config file changes nothing until the server is reloaded and the file is actually included.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

Validate configuration before reloading: nginx -t, apachectl configtest, caddy validate. This catches syntax errors without dropping traffic.
Dump the fully resolved configuration with nginx -T to see what is actually in effect, including every include.
Read the error log, not the access log, for 5xx causes. nginx names the failing upstream and the exact filesystem path it could not open.
For permission errors, test as the server user: sudo -u www-data cat /path/to/file. Check execute bits on every parent directory.
For binding failures, find the current listener with ss -tulpn | grep :80. Ports below 1024 need privileges or a capability such as CAP_NET_BIND_SERVICE.

Tools worth reaching for

nginx -t / nginx -T
apachectl configtest
ss -tulpn
tail -f error.log
sudo -u www-data

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

nginx.org

Related WebServer errors

See all 10 WebServer errors →

Browse other categories

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.