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

- Link: https://binariocero.com/linux/como-solucionar-el-error-proxy_buffer_size-is-not-enough-for-cache-key-en-nginx
- Published: 2025-09-07T07:24:37+02:00
- Author: Juan José Fernández Durán

![Loading](https://binariocero.com/wp-content/plugins/page-views-count/ajax-loader-
2x.gif)

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:

    ```wp-block-code
    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:

    ```wp-block-code
    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

 1. Editar el archivo de configuración principal de Nginx (`/etc/nginx/nginx.conf` 
    o `/etc/nginx/conf.d/*.conf`).
 2. Añadir o modificar las directivas anteriores en el bloque `http {}` o `server {}`.
 3. Verificar la sintaxis de la configuración: 
    `nginx -t`
 4. 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.