Debian/Ubuntu: Nginx upstream sent too big header при PHP — причины и исправление

Ошибка upstream sent too big header while reading response header from upstream в Nginx на Debian/Ubuntu почти всегда означает одно: бэкенд вернул слишком большой набор HTTP-заголовков, а Nginx не смог уместить их в выделенные буферы. На практике это чаще всего всплывает в связке Nginx + PHP-FPM, реже — когда Nginx работает как reverse proxy к другому приложению.

Симптом обычно выглядит знакомо: сайт открывается, но после авторизации, перехода в админку, включения нового плагина или обработки крупной сессии пользователь получает 502 Bad Gateway. В журнале ошибок Nginx при этом появляется строка про слишком большой заголовок от upstream.

Главная мысль здесь простая: увеличивать буферы стоит только после понимания, кто именно раздувает заголовки. Очень часто виноват не сам Nginx, а приложение, которое складывает в cookie слишком много данных, плодит заголовки Set-Cookie или добавляет лишние служебные заголовки после редиректов.

Ниже разберём, как диагностировать проблему на Debian/Ubuntu, какие параметры отвечают за чтение заголовков от PHP и proxy-бэкендов, чем отличаются fastcgi_buffer_size и proxy_buffer_size, и что делать, если корень проблемы не в веб-сервере, а в приложении.

Что именно означает эта ошибка

Когда Nginx работает с PHP-FPM, он передаёт запрос в FastCGI и читает ответ от PHP-процесса. Ответ начинается с заголовков: статус, Content-Type, Set-Cookie, иногда Location, заголовки кэша и политики безопасности. Если эта часть оказывается больше доступного буфера, Nginx пишет ошибку и отдаёт клиенту 502.

Если у вас не FastCGI, а обычный reverse proxy к Node.js, Python, Go, Apache или другому Nginx, логика остаётся той же, но участвуют уже директивы семейства proxy_buffer_size.

Важно: проблема почти никогда не связана с телом ответа. Поэтому изменение client_max_body_size и похожих лимитов в этой ситуации обычно не помогает.

Чаще всего причина одна из следующих:

• слишком большие или многочисленные cookie после логина;
• несколько заголовков Set-Cookie от CMS, фреймворка или middleware;
• часть данных сессии хранится в cookie;
• цепочка редиректов, где каждый шаг добавляет новые cookie;
• reverse proxy получает длинные служебные заголовки от приложения;
• плагины авторизации, SSO или модули аналитики раздувают ответ.

Где искать подтверждение на Debian/Ubuntu

Начните с журналов Nginx. На Debian/Ubuntu чаще всего это /var/log/nginx/error.log и access log конкретного сайта, если он задан отдельно.

sudo tail -n 100 /var/log/nginx/error.log
sudo grep -R "too big header" /var/log/nginx/error.log*

Обычно вы увидите строку примерно такого вида:

upstream sent too big header while reading response header from upstream, client: 203.0.113.10, server: example.com, request: "GET /admin HTTP/2.0", upstream: "fastcgi://unix:/run/php/php8.2-fpm.sock:"

Ключевой фрагмент здесь — источник upstream. Если видите fastcgi://, речь о PHP-FPM. Если там адрес приложения или сокет другого сервиса, смотреть нужно уже на proxy-настройки.

Полезно сразу понять, на каком URL всё ломается. Очень часто это не главная страница, а конкретный маршрут: вход в админку, callback авторизации, корзина, личный кабинет, API-ручка с обновлением токена.

Если ошибка появилась после изменений, проверьте, что именно менялось:

• обновление CMS, фреймворка или PHP-пакетов;
• включение плагина авторизации, аналитики или A/B-тестов;
• подключение reverse proxy перед приложением;
• смена механики сессий;
• переезд с Apache на Nginx.

Облачный VDS-сервер в России

Аренда виртуальных серверов с моментальным развертыванием инфраструктуры от 195₽ / мес

Подробнее

Если проект уже вырос из простого окружения и вам нужно гибко управлять Nginx, PHP-FPM и системными лимитами, обычно удобнее держать такие сайты на VDS, где можно спокойно настраивать веб-стек под свои сценарии.

Почему чаще всего виноваты cookie

Одна из самых частых причин — раздутые cookie. После логина количество и размер заголовков Set-Cookie резко растут, и именно тогда проявляется классический сценарий: до авторизации всё работает, после — 502.

Особенно часто это встречается в PHP-приложениях, где:

• в cookie кладут состояние интерфейса или длинные токены;
• используют несколько механизмов авторизации одновременно;
• каждый модуль добавляет собственный служебный cookie;
• сессии реализованы через cookie-heavy middleware;
• есть SSO, CSRF, feature flags и аналитические метки в одном наборе.

Сама PHP-сессия не обязательно хранится целиком в заголовках ответа, но PHP и приложение могут генерировать новый идентификатор сессии, дополнительные флаги cookie, а поверх этого фреймворк или CMS добавляет ещё несколько своих заголовков. В итоге получается уже не один компактный Set-Cookie, а набор довольно крупных строк.

Если приложение пишет большие данные прямо в cookie, повышение буферов лишь маскирует проблему. Сайт заработает, но вы получите рост размера запросов, лишнюю нагрузку и нестабильность на границе браузерных лимитов.

Как отличить FastCGI-проблему от proxy-проблемы

Эта ошибка часто ищется вместе с запросами про fastcgi_buffer_size и proxy_buffer_size, и это нормально: сообщение похоже, а вот исправление зависит от типа upstream.

Если backend — PHP-FPM

Смотрите параметры:

• fastcgi_buffer_size — размер буфера для первой части ответа, где как раз находятся заголовки;
• fastcgi_buffers — количество и размер дополнительных буферов;
• fastcgi_busy_buffers_size — объём буферов, которые могут быть заняты одновременно.

Если backend — reverse proxy

Нужны уже директивы:

• proxy_buffer_size;
• proxy_buffers;
• proxy_busy_buffers_size.

Если запрос уходит через fastcgi_pass, исправлять ситуацию только параметром proxy_buffer_size бесполезно. Это одна из самых частых ошибок при копировании советов из обсуждений.

Если у вас несколько пулов PHP-FPM для разных сайтов или версий PHP, полезно проверить, в какой именно пул уходит проблемный vhost. На эту тему может пригодиться материал про настройку нескольких PHP-FPM пулов в Nginx.

Быстрая диагностика конфигурации Nginx

Сначала найдите нужный server-блок и PHP location. На Debian/Ubuntu это обычно конфиги в /etc/nginx/sites-available/ и симлинки в /etc/nginx/sites-enabled/.

sudo nginx -T | less
sudo grep -R "fastcgi_pass|proxy_pass" /etc/nginx/sites-enabled /etc/nginx/conf.d

Если в location для PHP есть строка вида fastcgi_pass unix:/run/php/php8.2-fpm.sock;, настройка нужна именно через FastCGI-параметры.

Типичный PHP location может выглядеть так:

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

В таком случае правки можно вносить либо внутрь конкретного location, либо на уровне server, если вы понимаете область действия параметров и не хотите влиять на другие приложения.

Рабочее исправление для PHP-FPM

Начинайте с умеренных значений. Не нужно сразу выставлять огромные буферы в мегабайтах. Для большинства случаев хватает небольшого увеличения.

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
    fastcgi_buffer_size 32k;
    fastcgi_buffers 8 32k;
    fastcgi_busy_buffers_size 64k;
}

После изменения обязательно проверьте конфиг и перезагрузите Nginx.

sudo nginx -t
sudo systemctl reload nginx

Если ошибка сохраняется, можно поднять значения ещё на шаг, например до 64k. Но повышать их бесконечно не стоит: если приложение генерирует аномально большие заголовки, это уже симптом проблемы на уровне кода или архитектуры.

Рабочее исправление для reverse proxy

Если upstream — не PHP-FPM, а другое приложение, используйте семейство proxy-директив:

location / {
    proxy_pass http://127.0.0.1:8080;
    proxy_buffer_size 32k;
    proxy_buffers 8 32k;
    proxy_busy_buffers_size 64k;
}

Подход тот же: сначала минимально достаточное увеличение, затем повторная проверка сценария, на котором всё падало.

Надежные SSL-сертификаты

Мы предлагаем широкий спектр SSL-сертификатов от GlobalSign по самым низким ценам. Поможем с покупкой и установкой SSL бесплатно!

Подробнее

Если заодно приводите сайт в порядок после ошибок авторизации, редиректов и настроек безопасности, стоит проверить и SSL-сертификаты: корректный HTTPS и единая схема доступа часто упрощают поведение cookie и редиректов.

Как понять, что буферы помогли, но корень проблемы остался

Допустим, вы увеличили fastcgi_buffer_size, ошибка исчезла, и сайт снова работает. Это ещё не значит, что всё действительно исправлено. Если причина в огромных cookie, проблема просто перестала быть заметной на текущем объёме данных.

Насторожиться стоит, если:

• ошибка возникала только после авторизации;
• в ответе видно много Set-Cookie;
• каждый переход добавляет новые cookie;
• есть интеграция SSO или сложная внешняя авторизация;
• маршрут с ошибкой связан с личным кабинетом, корзиной или админкой.

Как посмотреть реальные заголовки ответа

Удобный способ — запросить проблемный URL локально и посмотреть ответные заголовки. Для простых случаев достаточно curl.

curl -I -s localhost
curl -k -I -s -H "Host: example.com" https://127.0.0.1/login

Если ответ выглядит нормально, но проблема воспроизводится только после входа в систему, смотрите заголовки уже в браузерных инструментах разработчика: количество строк Set-Cookie, их длину, повторение одних и тех же ключей, наличие чрезмерно длинных JWT или сериализованных значений.

Наиболее частые признаки нездоровой картины:

• один cookie занимает несколько килобайт;
• несколько cookie дублируют друг друга с разными префиксами;
• в cookie хранится JSON или сериализованная структура;
• после редиректа добавляются новые служебные токены без очистки старых.

Что делать на стороне PHP-приложения

Если у вас есть доступ к коду или настройкам CMS, правильнее не только увеличить буферы, но и уменьшить размер заголовков. Это особенно важно для долгосрочной стабильности.

Пересмотрите работу с cookie

Не храните в cookie то, что можно хранить на сервере. В идеале cookie должен содержать короткий идентификатор, а основное состояние — лежать в файловой, memory- или database-сессии.

Проверьте обработку сессий

Сам по себе PHPSESSID обычно компактен. Проблема чаще возникает в обвязке вокруг него: дополнительные токены, признаки экспериментов, трекинг или состояние интерфейса.

Сократите число заголовков Set-Cookie

Иногда несколько модулей добавляют отдельные cookie для одного и того же функционала. Часть из них можно объединить, часть — убрать, а часть перенести в серверное хранилище.

Проверьте редиректы после логина

Если вход вызывает цепочку из нескольких 302-ответов, на каждом этапе могут выставляться новые заголовки. Упрощение такого flow иногда решает проблему лучше любой настройки Nginx.

Если вы параллельно переносите сайт между серверами или меняете схему домена и HTTPS, полезно отдельно проверить редиректы, HSTS и SSL при миграции домена, потому что лишние переадресации часто усиливают подобные ошибки.

Частые ошибки при исправлении

• меняют client_max_body_size, хотя проблема не в теле запроса или ответа;
• увеличивают только proxy_buffer_size при использовании fastcgi_pass;
• правят один vhost, а трафик приходит в другой;
• забывают проверить итоговую конфигурацию через nginx -T;
• резко поднимают буферы везде, не ограничивая область действия;
• считают инцидент закрытым, не проверив реальные заголовки приложения.

Практический алгоритм устранения

1. Найдите точную строку ошибки в error.log и определите тип upstream.
2. Выясните URL и сценарий воспроизведения: логин, админка, callback, API.
3. Проверьте, не выросли ли cookie и число Set-Cookie.
4. Для PHP-FPM увеличьте fastcgi_buffer_size и связанные FastCGI-буферы умеренно.
5. Для reverse proxy настройте proxy_buffer_size и связанные proxy-буферы.
6. Проверьте конфиг через nginx -t и выполните reload.
7. Повторите проблемный сценарий.
8. Если сайт ожил, всё равно разберите причину раздувания заголовков на уровне приложения.

Пример с отдельным include-файлом

Если не хочется размазывать настройки по нескольким vhost, можно вынести их в отдельный snippet и подключать только там, где проблема реально есть.

sudo nano /etc/nginx/snippets/fastcgi-header-buffers.conf

fastcgi_buffer_size 32k;
fastcgi_buffers 8 32k;
fastcgi_busy_buffers_size 64k;

Дальше подключите snippet в нужном PHP location:

location ~ \.php$ {
    include snippets/fastcgi-php.conf;
    include snippets/fastcgi-header-buffers.conf;
    fastcgi_pass unix:/run/php/php8.2-fpm.sock;
}

Так конфиг проще сопровождать и легче откатывать, если изменения больше не нужны.

Итог

Ошибка nginx upstream sent too big header на Debian/Ubuntu в связке с PHP почти всегда указывает на слишком большой набор заголовков от приложения, а не на абстрактную поломку Nginx. В первую очередь проверяйте сценарии после логина, большие cookie, количество Set-Cookie и тип upstream.

Если у вас PHP-FPM, корректируйте fastcgi_buffer_size и связанные FastCGI-буферы. Если это reverse proxy — используйте proxy_buffer_size и proxy-буферы. Но не ограничивайтесь только конфигом веб-сервера: если заголовки раздувает само приложение, лучше сократить их размер, чем бесконечно расширять буферы.

Самый надёжный подход — сначала диагностировать, потом менять конфиг минимально достаточным образом и только после этого считать инцидент закрытым.