Nginx Error: could not build server_names_hash_max_size (hash bucket size too small) Linux / DevOps

Nginx: could not build server_names_hash_max_size — Решение

Обновлено: 18.08.2026 · Официальная база знаний

При проверке конфигурации (nginx -t) или запуске службы Nginx аварийно останавливается с ошибкой хеш-таблиц: could not build server_names_hash_max_size, you should increase server_names_hash_bucket_size: 64 или could not build optimal server_names_hash.

Параметр хеша	Значение по умолчанию	Назначение
`server_names_hash_bucket_size`	32, 64 или 128 байт	Размер одной ячейки (корзины) хеш-таблицы (привязан к размеру L1 Cache Line CPU)
`server_names_hash_max_size`	`512`	Максимальный суммарный размер хеш-таблицы имен виртуальных хостов
Длина доменного имени	Превышает размер bucket	Длинные домены (более 32-64 символов) не помещаются в ячейку

Nginx отказывается применять конфигурацию и не может запуститься (Job for nginx.service failed).
Сбой происходит после добавления множества новых поддоменов или доменных имен большой длины.

Откройте глобальный файл конфигурации /etc/nginx/nginx.conf.

Внутри блока http найдите или добавьте директивы настройки хеш-таблиц доменных имен:

http {
    # Увеличьте размер ячейки хеша (значение должно быть степенью двойки: 64, 128, 256):
    server_names_hash_bucket_size 128;
    server_names_hash_max_size 4096;

    # Если используется большое количество map или types, увеличьте и их:
    types_hash_max_size 2048;
    types_hash_bucket_size 128;
    ...
}

Если у вас используются сотни доменов в блоке server_name, увеличьте server_names_hash_bucket_size до 256.
Проверьте валидность исправленной конфигурации:
```
sudo nginx -t
```
Примените обновленные параметры: sudo systemctl reload nginx.

Низкоуровневая архитектура: Значение server_names_hash_bucket_size всегда должно быть строго кратно размеру строки процессорного кэша первого уровня (CPU L1 Cache Line — обычно 64 байта). Установка значений, не являющихся степенью двойки (например, 100), приведет к неэффективному расходу памяти и замедлению поиска по доменам.

Практический опыт инженера: В SaaS-платформах и мультиарендных сервисах (multi-tenant) с тысячами персональных поддоменов сразу прописывайте `server_names_hash_bucket_size 256;` в базовый шаблон Ansible/Puppet.

Частые вопросы (FAQ)

Почему эта ошибка не возникает при малом числе доменов?

При небольшом числе стандартных коротких доменов Nginx умещает структуру быстрого поиска в дефолтный размер корзины (32/64 байта). При росте числа доменов или их длины вероятность коллизий возрастает, и алгоритм хеширования требует расширения ячеек памяти.

Влияет ли увеличение bucket_size на потребление оперативной памяти?

Влияние минимально: хеш-таблицы занимают считанные килобайты памяти, но их увеличение кардинально ускоряет роутинг входящих HTTP-запросов между виртуальными хостами.

Что делать, если ошибка повторяется с variables_hash_bucket_size?

Аналогично добавьте директиву variables_hash_bucket_size 128; и variables_hash_max_size 2048; в блок http.

Как узнать размер кэш-линии процессора на Linux?

Выполните команду getconf LEVEL1_DCACHE_LINESIZE (обычно возвращает 64).