Si alguna vez has visto el error upstream sent too big header while reading response header from upstream en tus logs de Nginx, sabes lo frustrante que puede ser. La primera reacción de muchos, de hecho, es buscar ese mensaje y copiar el primer bloque de configuración que encuentran.
El problema es que la solución “obvia” no siempre es la buena. A menudo, la gente llega y empieza a subir los valores de fastcgi_buffers y fastcgi_buffer_size. Y sí, eso funciona si tu Nginx está proxying a un FastCGI, como PHP-FPM. Pero, ¿qué pasa si no es el caso?
Entendiendo el error: ¿De dónde viene el 'upstream'?
El mensaje es claro: Nginx está recibiendo una cabecera de respuesta (response header) de tu servidor upstream que es más grande de lo que espera o puede manejar con sus buffers configurados. La clave aquí es entender qué significa ese upstream en tu configuración.
En Nginx, upstream se refiere al servidor al que Nginx está enviando las peticiones. Puede ser de dos tipos principales que nos interesan para este error:
- FastCGI: Esto es común cuando Nginx sirve archivos estáticos y delega la ejecución de scripts (como PHP) a un proceso separado, generalmente PHP-FPM, usando
fastcgi_pass. - HTTP Proxy: Cuando Nginx actúa como un proxy inverso para otro servidor web completo (como Node.js, Python/Django, Java/Spring Boot, o incluso otro Nginx), usando
proxy_pass.
Si no sabes cuál estás usando, aumentar los buffers de FastCGI mientras tu problema está en un proxy HTTP no va a servir de nada. A mí esto me costó un poco al principio, lo admito.
La solución correcta: FastCGI vs. HTTP Proxy
Yo prefiero atacar el problema donde está. No me convence subir los buffers a lo loco si no sabes qué causa el problema o si solo estás enmascarando una cabecera gigante que tu aplicación no debería enviar. Primero, revisa tu configuración de Nginx. Busca fastcgi_pass o proxy_pass.
Si usas FastCGI (e.g., PHP-FPM)
Si Nginx está comunicándose con un servidor FastCGI, necesitarás ajustar las directivas fastcgi_buffers y fastcgi_buffer_size. Por defecto, Nginx es bastante conservador con esto. Un ejemplo:
http {
...
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
...
}
Aquí, fastcgi_buffers 16 16k indica 16 buffers de 16KB cada uno. fastcgi_buffer_size 32k es el tamaño del primer buffer para leer la cabecera. Es común que la cabecera sea el problema, así que ajustar el buffer_size es clave. Ojo, que aumentar esto implica más uso de memoria para Nginx.
Si usas un HTTP Proxy (e.g., Node.js, Django)
Si Nginx actúa como un proxy inverso para otro servidor HTTP, las directivas que te interesan son proxy_buffer_size y proxy_buffers. Es distinto al FastCGI.
http {
...
proxy_buffer_size 128k;
proxy_buffers 4 256k;
proxy_busy_buffers_size 256k;
...
}
En este caso, proxy_buffer_size es el buffer para la cabecera de la respuesta, y proxy_buffers define cuántos buffers y de qué tamaño se usarán para el cuerpo de la respuesta. También existe la opción de desactivar el buffering por completo con proxy_buffering off;, lo que a veces se usa para long polling, pero no te lo recomiendo para uso general, pues puede impactar el rendimiento y la estabilidad.
Mi recomendación concreta
Cuando te encuentres con este error, lo primero es identificar el tipo de upstream que Nginx está usando. Revisa tu archivo de configuración de Nginx (o los includes) y busca si usas fastcgi_pass o proxy_pass. Una vez que lo sepas, aplica los ajustes de buffer específicos para ese módulo.
No subas los buffers a valores altísimos sin un análisis previo. Si las cabeceras son excesivamente grandes, más allá de lo razonable, quizás el problema real esté en la aplicación upstream que las está generando. Pero para empezar, identifica y ajusta el buffer correcto.