Skip to main content

504 Gateway Timeout en NGINX: cómo solucionarlo

Este artículo es una traducción del original en inglés.


Todos los blogs parecen copiar y pegar la misma “solución” para los errores 504 Gateway Timeout NGINX: simplemente aumente todos los timeouts. Mal consejo. La mayoría de esas directivas no necesitan ajuste alguno; la solución real para los problemas de 504 Gateway Timeout NGINX implica entender qué capa está agotando el tiempo de espera y ajustar la única directiva que importa.

Entendiendo el problema del timeout 504

Un 504 Gateway Timeout ocurre cuando NGINX, actuando como proxy, no recibe una respuesta del servidor upstream dentro del período de timeout configurado. El timeout predeterminado es de 60 segundos (o 60000 ms internamente).

El upstream que causa el timeout podría ser:

  • Otro servidor HTTP (Node.js, Python, Ruby, Go)
  • Un proxy de caché como Varnish
  • PHP-FPM o cualquier proceso FastCGI
  • Cualquier backend que hable HTTP

La idea clave: solo necesita aumentar el timeout que realmente se está activando.

? ¿Qué directiva importa realmente?

Para el ngx_http_proxy_module (proxy a backends HTTP), existen tres directivas de timeout:

Directiva Predeterminado Qué controla
proxy_connect_timeout 60s Tiempo para establecer la conexión TCP
proxy_send_timeout 60s Tiempo entre escrituras sucesivas al upstream
proxy_read_timeout 60s Tiempo entre lecturas sucesivas del upstream

En el 99 % de los casos de 504 Gateway Timeout NGINX, proxy_read_timeout es el culpable. Su backend tarda en responder, no en aceptar conexiones.

La misma lógica se aplica a FastCGI:

Directiva Predeterminado Qué controla
fastcgi_connect_timeout 60s Tiempo para establecer la conexión FastCGI
fastcgi_send_timeout 60s Tiempo entre escrituras sucesivas
fastcgi_read_timeout 60s Tiempo entre lecturas sucesivas

Para aplicaciones PHP, fastcgi_read_timeout es casi siempre la que hay que aumentar.

?️ La forma correcta de solucionar los errores 504 Gateway Timeout NGINX

No aumente todos los timeouts a ciegas. Siga este enfoque de diagnóstico:

Paso 1: Identifique la capa que causa el timeout

Revise su registro de errores de NGINX:

tail -f /var/log/nginx/error.log | grep -i timeout

Verá mensajes como:

upstream timed out (110: Connection timed out) while reading response header from upstream

Esto le indica que es un problema de read timeout.

Paso 2: Revise su arquitectura

Si NGINX hace proxy a un backend HTTP (Varnish, Node.js, otro NGINX, etc.):

location / {
    proxy_pass http://127.0.0.1:6081;
    proxy_read_timeout 120s;  # Única directiva que normalmente necesita cambiarse
}

Si NGINX se comunica directamente con PHP-FPM:

location ~ .php$ {
    fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
    fastcgi_read_timeout 120s;  # La crítica para PHP
}

Paso 3: No olvide el backend real

Si ejecuta PHP, también debe asegurarse de que PHP mismo no agote el tiempo de espera antes que NGINX:

; En php.ini o en la configuración del pool de PHP-FPM
max_execution_time = 120

Específicamente para PHP-FPM:

; En /etc/php-fpm.d/www.conf
request_terminate_timeout = 120

? Arquitecturas de múltiples capas (el “sándwich de NGINX”)

Las configuraciones de producción a menudo se ven así:

Cliente → NGINX (TLS) → Varnish → NGINX (Backend) → PHP-FPM

Esto no se trata solo de Varnish; podría hacer proxy a Cualquier aplicación HTTP: Node.js, Python (Gunicorn/uWSGI), Ruby (Puma), Go, Java o incluso otra instancia de NGINX.

Cada capa tiene su propio timeout. La cadena se ve así:

  1. NGINX frontal (proxy_read_timeout) → timeout esperando a Varnish/backend
  2. Varnish (.first_byte_timeout) → timeout esperando al NGINX backend
  3. NGINX backend (fastcgi_read_timeout) → timeout esperando a PHP
  4. PHP-FPM (request_terminate_timeout) → termina el script PHP

La regla: cada capa externa debe tener un timeout ≥ la capa interna.

Timeouts de backend en Varnish

Si usa Varnish, configure el backend en su VCL:

vcl 4.1;

backend default {
    .host = "127.0.0.1";
    .port = "8080";
    .first_byte_timeout = 120s;  # Tiempo hasta el primer byte de respuesta
}

El .first_byte_timeout es el crítico: es cuánto tiempo espera Varnish a que el backend comience a responder.

? Ejemplos completos funcionales

NGINX con proxy a Node.js/Python/Go

upstream app_backend {
    server 127.0.0.1:3000;
}

server {
    listen 443 ssl http2;
    server_name example.com;

    location / {
        proxy_pass http://app_backend;
        proxy_http_version 1.1;

        # Aumente solo si su aplicación tiene endpoints lentos
        proxy_read_timeout 120s;

        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
    }
}

NGINX con PHP-FPM (sin Varnish)

location ~ .php$ {
    fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;

    # Para operaciones PHP lentas
    fastcgi_read_timeout 120s;
}

Administración de WordPress con timeouts extendidos

Las operaciones de administración de WordPress

 (importaciones, actualizaciones de plugins) a menudo necesitan más tiempo:

location ~ ^/wp-admin/.*.php$ {
    fastcgi_pass unix:/var/run/php-fpm/php-fpm.sock;
    fastcgi_param SCRIPT_FILENAME $document_root$fastcgi_script_name;
    include fastcgi_params;

    # Timeout mayor para operaciones de administración
    fastcgi_read_timeout 300s;
    fastcgi_param PHP_ADMIN_VALUE "memory_limit=512M n max_execution_time=300";
}

? Comandos de diagnóstico

Encontrar errores de timeout en NGINX


grep -i "timed out" /var/log/nginx/error.log | tail -20

Revisar el registro lento de PHP-FPM


Actívelo en la configuración de su pool:

slowlog = /var/log/php-fpm/slow.log
request_slowlog_timeout = 5s

Luego supervise:

tail -f /var/log/php-fpm/slow.log

Validar la configuración antes de recargar


nginx -t && systemctl reload nginx

⚠️ Errores comunes

Error 1: Aumentar proxy_connect_timeout para respuestas lentas

Esto solo afecta el establecimiento de la conexión. Si su backend tarda en procesar (no en aceptar conexiones), esto no ayudará.

Error 2: Establecer timeouts mayores que el max_execution_time de PHP

Si PHP termina el script a los 30 s pero NGINX espera 120 s, obtendrá un 502 (Bad Gateway) o una respuesta en blanco, no un 504.

Error 3: Olvidar las capas intermedias

En una configuración de múltiples capas, si Varnish tiene un timeout de 60 s pero NGINX tiene 120 s, Varnish agotará el tiempo primero y NGINX devolverá 503/504.

Error 4: Usar el mismo timeout alto en todas partes

No establezca proxy_read_timeout 600s de forma global. Use bloques location específicos para endpoints lentos. Consulte nuestra guía sobre la directiva location de NGINX

para dirigirse a URL específicas.

Entendiendo los mensajes de error

Mensaje

Causa

Solución

upstream timed out (110: Connection timed out) while reading proxy_read_timeout o fastcgi_read_timeout demasiado bajos Aumente el read timeout
upstream timed out (110: Connection timed out) while connecting proxy_connect_timeout demasiado bajo O backend caído Revise el backend, aumente el connect timeout
upstream prematurely closed connection El backend falló o PHP-FPM terminó el proceso Revise request_terminate_timeout

Relacionado: ajuste de buffers

Si ve errores 502 en lugar de 504, su problema podría ser el dimensionamiento de buffers de proxy en lugar de los timeouts. Los encabezados de respuesta grandes pueden provocar errores relacionados con buffers que se ven similares.

Resumen de buenas prácticas

  1. Diagnostique primero: revise los registros para identificar qué timeout se activa
  2. Aumente solo lo necesario: normalmente solo *_read_timeout
  3. Alinee la cadena: capas externas ≥ capas internas
  4. No enmascare problemas: si algo tarda 5 minutos, corrija el código, no solo aumente los timeouts
  5. Use anulaciones específicas por location: no aplique timeouts altos de forma global

Para la mayoría de las configuraciones, establecer proxy_read_timeout o fastcgi_read_timeout en 120 s resuelve el problema de 504 Gateway Timeout NGINX. Si necesita más, pregúntese por qué: la respuesta podría ser una optimización del código en lugar de un cambio de configuración.

Ajustar hoy soluciona el problema de hoy. La regresión de mañana lo deshace en silencio. GetPageSpeed Amplify ejecuta escaneos programados de gixy en cada host y vincula los hallazgos con métricas de tiempo de ejecución de NGINX en vivo. Compatible de forma directa con el obsoleto nginx-amplify-agent (fin de vida en enero de 2026).