Error 502 en nginx «upstream sent too big header»: solución

Nginx escribe «upstream sent too big header while reading response header from upstream» en el log y responde 502 Bad Gateway cuando las cabeceras de respuesta de tu aplicación (PHP-FPM, un contenedor, otro proxy) no caben en el único buffer que nginx reserva para ellas. Por defecto ese buffer ocupa una página de memoria, 4 KB en la mayoría de servidores Linux. La solución: aumenta fastcgi_buffer_size (para PHP-FPM) o proxy_buffer_size (para un proxy inverso) en la capa de nginx que registró el error y, después, averigua por qué las cabeceras crecieron tanto.
curl -s -o /dev/null -w '%{size_header}\n'; cualquier valor cercano a 4 KB fallará con la configuración por defecto. Donde nginx habla con PHP-FPM, pon fastcgi_buffer_size 32k; fastcgi_buffers 16 16k;; donde reenvía a otro servidor, proxy_buffer_size 32k; proxy_buffers 8 16k; proxy_busy_buffers_size 64k;, ejecuta nginx -t y recarga. Con dos capas de nginx (un proxy en el host delante de un contenedor) cambias la que muestra el error en su log, y al arreglar la interna suele fallar a continuación la externa. Luego reduce las cabeceras en origen: las sesiones guardadas en la cookie y la cabecera Link de precarga de Laravel son las causas habituales.¿Qué significa «upstream sent too big header»?
El servidor de destino (upstream) envió una línea de estado y unas cabeceras más grandes que el buffer en el que nginx lee el principio de la respuesta, así que nginx considera la respuesta inválida y devuelve 502 al cliente. «Upstream» es cualquier cosa a la que nginx reenvía la petición: PHP-FPM por FastCGI, un servidor de aplicaciones por HTTP u otro nginx.
La documentación del módulo FastCGI lo explica directamente: el buffer para la primera parte de la respuesta suele contener una cabecera pequeña y, si la cabecera supera su tamaño, la respuesta se considera inválida. El valor por defecto es una página de memoria, es decir, 4K u 8K según la plataforma. El módulo proxy aplica la misma regla a proxy_buffer_size. En Linux x86-64 una página ocupa 4.096 bytes; compruébalo con getconf PAGESIZE.
Un único buffer por conexión (fastcgi_buffer_size, proxy_buffer_size y sus equivalentes uwsgi_, scgi_ y grpc_) que debe contener a la vez la línea de estado y todas las cabeceras de la respuesta. El cuerpo puede pasar a otros buffers o a un archivo temporal; las cabeceras no.
Tres cosas que este error no es. No tiene que ver con la petición: cabeceras o cookies demasiado grandes enviadas por el navegador dan un 400 «Request Header Or Cookie Too Large», que controla large_client_header_buffers. No tiene que ver con el cuerpo: una página HTML de 5 MB pasa sin problema por el mismo buffer de cabeceras de 4 KB. Y desactivar el buffering no ayuda: con proxy_buffering off nginx sigue leyendo las cabeceras en un buffer de tamaño proxy_buffer_size.
¿Cómo confirmas que es este error?
Busca la línea exacta en el log de errores de nginx del servidor que devolvió el 502 y luego mide con curl las cabeceras de la URL que falla. Un 502 tiene varias causas posibles y la línea del log las distingue.
# nginx instalado en el host
sudo grep "too big header" /var/log/nginx/error.log | tail -n 3
# nginx en Docker (la imagen oficial envía el log de errores a stderr)
docker compose logs webserver 2>&1 | grep "too big header" | tail -n 3
Esta es la línea que obtuvimos de un contenedor nginx:alpine sin modificar (nginx 1.31.8) delante de php:8.3-fpm-alpine, cuando un script PHP envió 4 KB de cabeceras Set-Cookie:
[error] 21#21: *25 upstream sent too big header while reading response header from upstream, client: 172.18.0.4, server: , request: "GET /index.php?kb=8 HTTP/1.1", upstream: "fastcgi://172.18.0.2:9000", host: "127.0.0.1"
Fíjate en el campo upstream:. fastcgi:// significa que este nginx habla con PHP-FPM y necesita las directivas fastcgi_; http:// significa que reenvía a otro servidor HTTP y necesita las directivas proxy_.
Mide las cabeceras
El navegador no puede mostrarte las cabeceras de un 502, porque nginx las descartó. Pregunta directamente al backend, saltándote la capa que falla, y cuenta los bytes:
# bytes totales de cabeceras de una respuesta (en formato HTTP/1)
curl -s -o /dev/null -w '%{size_header}\n' http://127.0.0.1:8080/login
# las cabeceras, de mayor a menor
curl -s -o /dev/null -D - http://127.0.0.1:8080/login | awk '{ print length($0), $1 }' | sort -rn | head
Usa GET, no curl -I: algunas aplicaciones responden a HEAD con cabeceras distintas. Repite la medición con las cookies de una sesión iniciada (-b 'laravel_session=…'), porque las cabeceras más grandes suelen aparecer solo tras el login o en una página concreta. Si el total se acerca a 4.096 bytes o los supera, ya tienes la causa.
| Línea del log de errores | Código | Qué suele significar |
|---|---|---|
| upstream sent too big header while reading response header from upstream | 502 | Cabeceras de respuesta mayores que *_buffer_size |
| connect() failed (111: Connection refused) while connecting to upstream | 502 | Nada escucha en la dirección del upstream (backend caído o IP de contenedor obsoleta) |
| upstream prematurely closed connection while reading response header from upstream | 502 | El proceso del backend murió o cerró la conexión a mitad de la petición |
| upstream timed out (110: Connection timed out) while reading response header from upstream | 504 | Backend demasiado lento; un problema de tiempo de espera, no de buffer |
Datos a noviembre de 2026, nginx 1.31.8. Las dos primeras líneas las reprodujimos en nuestro entorno de pruebas; las demás son mensajes estándar de nginx.
¿Por qué crecen tanto las cabeceras de respuesta?
Casi siempre por una de cuatro cosas: cookies, cabeceras Link de precarga, tokens o cabeceras de depuración. Una respuesta típica sin ellas queda muy por debajo de 1 KB, así que para llegar a 4 KB algo tiene que crecer.
- Sesiones en la cookie. Con el driver de sesión
cookiede Laravel, las sesiones se guardan en cookies seguras y cifradas (documentación de Laravel). Todo lo que guardas en la sesión, incluidos los datos flash y los valores antiguos de formularios, vuelve cifrado comoSet-Cookieen cada respuesta. El cifrado y base64 hacen que la cookie pese más que los propios datos. Los navegadores solo están obligados a aceptar «al menos 4096 bytes por cookie» (RFC 6265, sección 6.1), de modo que una sesión en cookie puede acercarse por sí sola al buffer por defecto de nginx. - Muchas cabeceras Set-Cookie. Sesión, token CSRF, «recordarme», consentimiento de cookies, pruebas A/B y analítica: cada cookie es una cabecera aparte con sus propios atributos
Path,Expires,SameSiteySecure. - Cabeceras Link de precarga. El middleware
AddLinkHeadersForPreloadedAssetsde Laravel escribe en una sola cabeceraLinkcada script y hoja de estilos que el helper de Vite marcó para precarga (código del framework). Los starter kits oficiales de Laravel añaden este middleware al grupo web (starter kit de Vue). Una página dividida en más de 25 chunks con URL absolutas produce una cabecera de varios kilobytes. - Tokens y datos de depuración. JWT en cookies o cabeceras propias, cabeceras Content-Security-Policy con listas largas de dominios y barras de desarrollo que envían datos en cabeceras.
Como las cookies dependen de la sesión y las cabeceras de precarga de la página, el error suele afectar solo a algunas URL y a parte de los usuarios. «Navegando dentro de la app funciona, al recargar la página da 502» es la señal típica de la cabecera Link: la navegación interna de una SPA pide JSON, mientras que una carga completa devuelve HTML con todos los chunks precargados en la cabecera.
fastcgi_buffer_size o proxy_buffer_size: ¿cuál cambias?
El módulo que corresponde al upstream: de la línea del log: fastcgi_buffer_size donde nginx pasa las peticiones a PHP-FPM con fastcgi_pass, y proxy_buffer_size donde las reenvía con proxy_pass. Cambiar la otra no sirve de nada.
| Directiva | Se usa con | Por defecto (bytes) | Nuestro valor |
|---|---|---|---|
fastcgi_buffer_size | fastcgi_pass (PHP-FPM) | 4k u 8k (una página) | 32k |
fastcgi_buffers | fastcgi_pass | 8 × 4k u 8k | 16 16k |
fastcgi_busy_buffers_size | fastcgi_pass | 8k o 16k | por defecto, salvo que nginx -t se queje |
proxy_buffer_size | proxy_pass (upstream HTTP) | 4k u 8k (una página) | 32k |
proxy_buffers | proxy_pass | 8 × 4k u 8k | 8 16k |
proxy_busy_buffers_size | proxy_pass | 8k o 16k | 64k |
Valores por defecto de la documentación de los módulos FastCGI y proxy de nginx, a noviembre de 2026.
Para PHP-FPM:
location ~ \.php$ {
fastcgi_pass php:9000;
include fastcgi_params;
fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
# Cabeceras de respuesta de hasta 32 KB en lugar de una página de 4 KB
fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;
}
Para un proxy inverso:
location / {
proxy_pass http://127.0.0.1:8080;
proxy_set_header Host $host;
proxy_buffer_size 32k;
proxy_buffers 8 16k;
proxy_busy_buffers_size 64k;
}
Por qué subir solo el tamaño del buffer hace fallar nginx -t
Si añades solo proxy_buffer_size 16k (o fastcgi_buffer_size 32k) y dejas *_buffers 8 4k por defecto, la prueba de configuración se niega a arrancar. Obtuvimos exactamente esto:
nginx: [emerg] "proxy_busy_buffers_size" must be less than the size of all "proxy_buffers" minus one buffer in /etc/nginx/nginx.conf:32
nginx: configuration file /etc/nginx/nginx.conf test failed
La razón está en la descripción de proxy_busy_buffers_size: por defecto su tamaño se limita a dos buffers definidos por proxy_buffer_size y proxy_buffers. Al subir el buffer de cabeceras a 16k, el valor «busy» por defecto sube a 32k, más que los 8 × 4k = 32k de buffers del cuerpo menos un buffer. Sube proxy_buffers a la vez (8 16k pasa) y, si defines proxy_busy_buffers_size de forma explícita, mantenlo por debajo del total de proxy_buffers menos un buffer: con 4 × 16k, 32k pasó y 64k falló con el mismo mensaje. El módulo FastCGI da el mismo error con nombres fastcgi_. Ojo: el mensaje apunta a nginx.conf, no al archivo que editaste.
¿Qué tamaño es seguro?
El necesario para tus cabeceras medidas, con margen, y no más. Estos buffers se asignan por conexión: el de cabeceras en cada petición reenviada y los demás según los necesite el cuerpo de la respuesta. 32k cubre de sobra cualquier aplicación razonable. Si necesitas 64k o más, algo está generando cabeceras con las que también tendrán problemas los navegadores y las CDN, y la corrección corresponde a la aplicación.
Dos capas de nginx: ¿cuál hay que cambiar?
La capa en cuyo log de errores aparece la línea. En una instalación típica con Docker, el nginx del host termina HTTPS y reenvía a un contenedor con nginx, que pasa las peticiones PHP a PHP-FPM. Cada capa tiene sus propios 4 KB por defecto y cada una responde 502.
Montamos esa cadena con imágenes sin modificar (proxy como en el host → nginx:alpine → php:8.3-fpm-alpine) e hicimos que el script PHP enviara cada vez más cabeceras Set-Cookie de 1 KB:
| Cabeceras extra (KB) | nginx interno, FastCGI por defecto | nginx interno, fastcgi_buffer_size 32k | Proxy externo por defecto (interno a 32k) | Proxy externo, proxy_buffer_size 32k |
|---|---|---|---|---|
| 3 | ✓ 200 | ✓ 200 | ✓ 200 | ✓ 200 |
| 4 | ✗ 502 | ✓ 200 | ✗ 502 | ✓ 200 |
| 10 | ✗ 502 | ✓ 200 | ✗ 502 | ✓ 200 |
| 31 | ✗ 502 | ✓ 200 | ✗ 502 | ✓ 200 |
| 33 | ✗ 502 | ✗ 502 | ✗ 502 | ✗ 502 |
Medido el 16 de noviembre de 2026, nginx 1.31.8, PHP 8.3 FPM, página de memoria de 4.096 bytes. Una respuesta con 6 KB de cookies extra tenía, según curl, 6.346 bytes de cabeceras.
De aquí salen dos lecciones prácticas. Primera: arreglar la capa interna desplaza el fallo hacia fuera. Tras subir el buffer FastCGI, las mismas peticiones fallaban en el proxy externo, con upstream: "http://…" en su log, y el navegador veía el mismo 502. Segunda: la capa externa transmite lo que devuelve la interna, así que si ambas son pequeñas, el error solo aparece en el log interno hasta que lo corriges. Revisa los dos logs en cada prueba.
ℹ️ Nota: Los balanceadores de carga y las CDN delante de nginx tienen sus propios límites de cabeceras, que no siempre puedes cambiar. Otro motivo para corregir las cabeceras en origen en lugar de subir buffers en cada salto.
¿Cómo reduces las cabeceras en origen?
Guarda las sesiones en el servidor, envía menos enlaces de precarga y deja de meter datos en cookies. Los buffers más grandes eliminan el 502; las cabeceras más pequeñas abaratan cada petición y te alejan de los límites que haya más adelante en la cadena.
Saca las sesiones de la cookie
En Laravel, cambia el driver de sesión de cookie a redis o database. El navegador conserva entonces solo el ID de sesión.
# .env
SESSION_DRIVER=redis # o: database (necesita la tabla sessions)
php artisan config:clear
Cambiar de driver cierra la sesión de todos una vez, porque las sesiones existentes siguen en el almacén anterior. Con el driver database, asegúrate de que existe la tabla sessions (php artisan make:session-table y php artisan migrate en las versiones de Laravel que no la incluyen).
Limita la cabecera Link
Desde Laravel 12 el middleware acepta un límite: AddLinkHeadersForPreloadedAssets::using(8) incluye solo los 8 primeros recursos (código). Nada más cambia: la directiva @vite sigue escribiendo en el HTML una etiqueta <link rel="modulepreload"> para cada chunk.
// bootstrap/app.php
use Illuminate\Http\Middleware\AddLinkHeadersForPreloadedAssets;
->withMiddleware(function (Middleware $middleware) {
$middleware->web(append: [
AddLinkHeadersForPreloadedAssets::using(8),
]);
})
En Laravel 10 y 11 el middleware no tiene el método using(). Ahí puedes quitarlo del grupo web (las etiquetas de precarga del HTML se mantienen) o actualizar el framework.
Revisa las cookies
- Elimina las cookies que ya nadie lee y no vuelvas a enviar la misma cookie en cada respuesta si su valor no ha cambiado.
- Mantén los tokens fuera de las cookies cuando puedas, o con pocos claims; un JWT con datos de perfil es un problema de cabeceras esperando a ocurrir.
- Las cookies de scripts de terceros que el servidor no necesita, defínelas en el navegador o en un subdominio aparte.
✅ Ventajas de corregir en origen
- Arregla todas las capas a la vez, incluidas las CDN que no controlas
- Peticiones y respuestas más pequeñas en cada visita
- Sin memoria extra por conexión en el proxy
❌ A tener en cuenta
- Cambiar el driver de sesión cierra la sesión de los usuarios una vez
- Requiere un despliegue; cambiar el buffer, solo una recarga
- Las cookies de terceros pueden quedar fuera de tu control
¿Cómo aplicas el cambio y lo compruebas?
Edita la configuración, ejecuta nginx -t, recarga y repite la petición que fallaba mientras miras el log. Una recarga aplica la nueva configuración sin cortar las conexiones abiertas.
- Prueba la configuración
sudo nginx -ten el host odocker compose exec webserver nginx -ten un contenedor. Corrige cualquier[emerg]antes de seguir. - Recarga
sudo systemctl reload nginx(osudo nginx -s reload); en Docker,docker compose exec webserver nginx -s reload. - Confirma la configuración en uso
nginx -Tmuestra la configuración que nginx cargó realmente.docker compose exec webserver nginx -T | grep -n bufferdebe mostrar tus nuevos valores en el nivel esperado. Unfastcgi_buffer_sizedentro de unlocationanidado sustituye al deserverohttp. - Repite la petición que fallaba
Misma URL y mismas cookies que antes; esperas un 200 y ninguna línea nueva de «too big header» en los logs de ambas capas.
⚠️ Atención: En Docker, un archivo de configuración montado por separado (./default.conf:/etc/nginx/conf.d/default.conf) queda ligado al inodo del archivo. Las herramientas que guardan escribiendo un archivo nuevo y renombrándolo, comosed -i, dejan al contenedor leyendo la versión antigua: en nuestra prueba,nginx -ty la recarga funcionaron mientras el contenedor seguía sin las líneas de buffer. Compruébalo connginx -Ty reinicia el contenedor (docker compose restart webserver) si falta el cambio.
La misma corrección en NetSendo
NetSendo, una plataforma de email marketing autoalojada basada en Laravel, se encontró con este error en su editor de mensajes y lo corrigió por los dos lados en la versión 2.2.1 (7 de noviembre de 2026). Según el changelog, al cargar el editor directamente se obtenía un 502 porque la cabecera Link listaba unos 27 chunks y, junto con las cookies, empujaba las cabeceras por encima del buffer FastCGI de 4 KB de nginx.
- La aplicación usa ahora
AddLinkHeadersForPreloadedAssets::using(8), que según el changelog mantiene las cabeceras de cada página en unos 2 KB. Viene incluido en la imagen de Docker. docker/nginx/default.confdefine ahorafastcgi_buffer_size 32kyfastcgi_buffers 16 16k. Las instalaciones existentes conservan su copia de ese archivo hasta que la sustituyan, así que compárala con la versión actual del repositorio después de actualizar.- Las sesiones se guardan en Redis por defecto (
SESSION_DRIVER=redisen.env.example), así que la cookie de sesión solo contiene un ID. - El proxy inverso del host descrito en la documentación de configuración usa los buffers de proxy por defecto de nginx. Con cabeceras de 2 KB es suficiente; si su log llega a mostrar «too big header», añade las tres líneas
proxy_de arriba.
Otro 502 tras actualizar NetSendo, con «connect() failed (111: Connection refused)» en el log, se debía a una dirección de contenedor obsoleta y está corregido desde la versión 2.11.1. Para instalaciones nuevas, sigue el inicio rápido.
🎯 Consejos de experto
fastcgi:// o http:// en la línea del log te dice qué familia de directivas cambiar antes de tocar nada.
Las peticiones anónimas suelen llevar la mitad de las cookies. Copia la cookie de sesión del navegador y repite la medición con curl usando -b.
Arreglar el nginx interno traslada el 502 al proxy externo. Sigue los logs de errores de ambas capas mientras pruebas.
Añade a tu monitorización una comprobación con curl de %{size_header} en tu página más pesada, con alerta por encima del 75 % del buffer, para que una cookie nueva o un bundle más grande no te sorprendan en producción.
Preguntas frecuentes
¿Qué causa el error upstream sent too big header en nginx?
El upstream (PHP-FPM, un servidor de aplicaciones u otro proxy) envió cabeceras de respuesta más grandes que el buffer en el que nginx las lee, por defecto una página de memoria, es decir, 4 KB. Las causas habituales son cookies grandes o numerosas, sesiones guardadas en la cookie y cabeceras Link de precarga largas.
¿Debo cambiar fastcgi_buffer_size o proxy_buffer_size?
Mira el campo upstream de la línea del log. fastcgi:// indica que nginx habla con PHP-FPM, así que cambias fastcgi_buffer_size y fastcgi_buffers; http:// indica un proxy, así que cambias proxy_buffer_size, proxy_buffers y proxy_busy_buffers_size.
¿Qué valor de proxy_buffer_size es seguro?
32k basta para casi cualquier aplicación, junto con proxy_buffers 8 16k y proxy_busy_buffers_size 64k. Mide antes tus cabeceras reales; si necesitas 64k o más, corrige mejor la aplicación.
¿Por qué falla nginx -t después de subir proxy_buffer_size?
Un buffer de cabeceras mayor también sube el valor por defecto de proxy_busy_buffers_size, que debe quedar por debajo del total de proxy_buffers menos un buffer. Sube proxy_buffers a la vez, por ejemplo a 8 16k.
¿proxy_buffering off soluciona upstream sent too big header?
No. Incluso con el buffering desactivado, nginx lee las cabeceras de respuesta en un buffer de tamaño proxy_buffer_size, así que el límite de cabeceras no cambia.
Fuentes
- nginx: ngx_http_fastcgi_module
- nginx: ngx_http_proxy_module
- nginx: large_client_header_buffers (ngx_http_core_module)
- Laravel framework: AddLinkHeadersForPreloadedAssets middleware (12.x)
- Laravel Vue starter kit: bootstrap/app.php
- Laravel documentation: HTTP Session
- RFC 6265: HTTP State Management Mechanism (section 6.1, limits)
- NetSendo CHANGELOG (2.2.1: message editor 502 fix)
Email marketing en tu propio servidor
NetSendo se instala con Docker Compose y ya incluye la configuración de nginx descrita arriba.




