Cómo solucionar el error "proxy_buffer_size is not enough for cache key" en Nginx

Al configurar Nginx como proxy inverso con caché (por ejemplo, delante de Apache o PHP-FPM para aplicaciones como WordPress), uno de los problemas más frecuentes es encontrarse con errores relacionados con el tamaño de los buffers.

Un mensaje típico en los registros de Nginx es:

proxy_buffer_size 8192 is not enough for cache key, it should be increased to at least 11264

Este error indica que el espacio de memoria asignado para construir la clave de caché no es suficiente y está siendo truncado.

¿Qué significa este error?

Nginx utiliza un parámetro llamado proxy_cache_key para definir la clave única de cada objeto cacheado. Esa clave puede incluir:

La URL completa solicitada.
Los parámetros de la query string.
Cabeceras HTTP adicionales, si se incluyen en la definición de la clave.

Cuando la clave es demasiado larga (por ejemplo, URLs con muchos parámetros o configuraciones personalizadas de caché), el buffer de cabeceras (proxy_buffer_size) puede quedarse corto.

Por defecto, Nginx asigna 8 KB (8192 bytes) en arquitecturas de 64 bits y 4 KB en 32 bits. Si la clave supera ese tamaño, aparece el error.

Parámetros implicados

Los principales parámetros de configuración relacionados son:

proxy_buffer_size
Define el tamaño de un buffer para almacenar cabeceras de respuesta desde el servidor upstream. También se utiliza para la construcción de la clave de caché.
proxy_buffers
Número y tamaño de los buffers que almacenan respuestas del servidor backend.
proxy_busy_buffers_size
Tamaño máximo de memoria que puede estar ocupada al mismo tiempo por buffers "ocupados" mientras la respuesta sigue en proceso.

Solución

El mensaje de error indica explícitamente el tamaño mínimo requerido. En el ejemplo, se necesita 11264 bytes, por lo que aumentar proxy_buffer_size a 16k soluciona el problema.

Ejemplo de configuración:

http {
    # Buffer para cabeceras y cache key
    proxy_buffer_size 16k;

    # Número y tamaño de buffers para las respuestas del backend
    proxy_buffers 8 16k;

    # Tamaño máximo de buffers ocupados simultáneamente
    proxy_busy_buffers_size 32k;

    # ... resto de configuración ...
}

Pasos para aplicar cambios

Editar el archivo de configuración principal de Nginx (/etc/nginx/nginx.conf o /etc/nginx/conf.d/*.conf).
Añadir o modificar las directivas anteriores en el bloque http {} o server {}.
Verificar la sintaxis de la configuración:

nginx -t
Recargar Nginx sin interrumpir el servicio:

systemctl reload nginx

Buenas prácticas

Subir todos los buffers al doble: si ya tienes un ajuste en 8k, puedes subir proxy_buffer_size, proxy_buffers y proxy_busy_buffers_size a 16k o incluso más, para evitar problemas similares en el futuro.
No abusar de los buffers: aunque la memoria que consumen es baja en servidores modernos, un valor excesivamente alto podría ser innecesario si las URLs y cabeceras no son tan grandes.
Monitorizar logs de Nginx: si vuelves a ver mensajes de truncamiento, ajusta de nuevo el tamaño hasta un nivel estable.

Conclusión

El error "proxy_buffer_size is not enough for cache key" ocurre porque el tamaño por defecto de los buffers de Nginx no es suficiente para claves de caché largas.

La solución es simple: aumentar proxy_buffer_size a 16k o más, y ajustar también proxy_buffers y proxy_busy_buffers_size para mantener coherencia. De esta forma, Nginx podrá manejar claves más largas sin truncarlas y la caché funcionará de manera óptima.