Tecnología · GUÍA PRÁCTICA
¿NGINX dice “upstream sent too big header”? Identifique protocolo y dueño antes de ampliar buffers
Demuestre si la ruta usa proxy, FastCGI o uWSGI; mida headers reales, reduzca cookies o metadatos descontrolados y ajuste solo el buffer dueño.
El error pertenece al header de respuesta del upstream, no al cuerpo de carga ni al límite de headers del cliente. Tampoco prueba que todos los buffers deban crecer.
Conserve una petición fallida, imprima la location efectiva, identifique el módulo, mida bytes y reduzca el campo anómalo. Ajuste solo un límite legítimo y acotado.
Conserve la petición y la ruta efectiva
Guarde la línea completa del error de NGINX, timestamp, request ID, host, URI, status, dirección upstream y PID del worker. Correlaciónela con logs de access, aplicación y autenticación sin registrar valores secretos de cookies.
Ejecute nginx -T en la misma imagen o host que está sirviendo tráfico y archive el server y location resultantes tras expandir includes. Registre master PID, ruta de config y revisión desplegada; editar un archivo que ningún worker cargó no es una corrección.
Identifique el protocolo antes de elegir directivas
El error pertenece a la respuesta del upstream. Si la location usa proxy_pass, revise proxy_buffer_size; fastcgi_pass y uwsgi_pass tienen familias propias. client_max_body_size y large_client_header_buffers controlan otros límites del lado de la petición.
Use el esquema upstream del error y la location efectiva, no un fragmento genérico. Cambiar proxy_* no afecta una petición atendida por FastCGI o uWSGI, y un ajuste global puede aumentar memoria en todas las rutas sin necesidad.
Mida el dueño del response header
Reproduzca la ruta con el mismo estado de autenticación y sesión en un entorno seguro o acceso directo al upstream. Capture nombres y longitudes en bytes ocultando valores; revise Set-Cookie repetidos, Location, metadatos de autenticación y campos personalizados.
Compare una respuesta que pasa con otra que falla. Determine si un campo supera el first-response buffer o si se acumulan varios. Si el crecimiento viene de sesión, OAuth state o datos serializados, corríjalo en el productor cuando sea posible.
Aplique el cambio mínimo del módulo
Reduzca cookies duplicadas o grandes, mueva sesiones voluminosas al servidor, elimine metadatos innecesarios y acote redirect/auth state. Si un header legítimo sigue siendo mayor, aumente solo el buffer del módulo correcto en el contexto efectivo más estrecho.
Mantenga válidas las restricciones de proxy_buffers y busy buffers al cambiar buffering, pero no las use como sustituto de medir el primer header. Valide sintaxis, recargue suavemente y verifique que el worker activo heredó la configuración renderizada.
Repita el mismo estado y valide memoria acotada
Repita URI, método, upstream, callback de autenticación y tamaño de sesión. Confirme respuesta distinta de 502, error log limpio y resultado correcto; pruebe además casos cerca y por encima del límite para conocer la frontera.
Registre directivas anteriores y nuevas, location efectiva, resumen de bytes, hora de reload, request ID, concurrencia, impacto de memoria y umbral de rollback. Vigile el crecimiento tras login o expansión del carrito para que el nuevo buffer no solo posponga un bug sin límite.
