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í:
- NGINX frontal (
proxy_read_timeout) → timeout esperando a Varnish/backend - Varnish (
.first_byte_timeout) → timeout esperando al NGINX backend - NGINX backend (
fastcgi_read_timeout) → timeout esperando a PHP - 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
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
- Diagnostique primero: revise los registros para identificar qué timeout se activa
- Aumente solo lo necesario: normalmente solo
*_read_timeout - Alinee la cadena: capas externas ≥ capas internas
- No enmascare problemas: si algo tarda 5 minutos, corrija el código, no solo aumente los timeouts
- 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).