Solucionar nginx 504 Gateway Time-out: encontrar la causa en vez de subir el plazo

Un 504 Gateway Time-out es la más paciente de todas las páginas de error. nginx aceptó la petición, la pasó al backend y luego esperó hasta que venció un plazo fijado internamente. El backend estuvo accesible todo el tiempo, solo que no respondió a tiempo. Ahí está justamente la diferencia con el código vecino: en el 502 Bad Gateway el backend responde mal o no responde en absoluto, mientras que en el 504 responde demasiado despacio. Esta guía te enseña cómo medir dónde se consume realmente el tiempo, cuál de los muchos plazos es el que acaba aplicándose y por qué subir ese límite es casi siempre la peor de las respuestas disponibles.

Todos los datos se refieren a Debian 13 (trixie), Debian 12 (bookworm), Ubuntu 24.04 LTS y Ubuntu 22.04 LTS. Los comandos están escritos para trabajar como root; si trabajas como usuario normal, antepón sudo. En los ejemplos aparece PHP 8.4, así que sustituye el número de versión por el de tu sistema:

ls /etc/php/

Las directivas de nginx se llaman igual en los cuatro sistemas. Las diferencias están del lado de PHP y de la base de datos, y quedan señaladas en los puntos correspondientes.

Quién se ha rendido decide en qué dirección buscar

Antes de abrir ningún archivo, responde a una pregunta: ¿qué capa ha cortado? El código de estado ya lo delata.

La fila del 499 es la más infravalorada. No es un error, sino un sistema de alerta temprana: el visitante cerró la pestaña porque la página tardaba demasiado. Si un 504 desaparece después de subir el plazo y en su lugar empiezan a salir 499, no se ha resuelto nada.

awk '{print $9}' /var/log/nginx/access.log | sort | uniq -c | sort -rn | head

El campo 9 corresponde al formato estándar combined. Muchos 504 con pocos 499 apuntan a páginas pesadas concretas; la imagen contraria, a una aplicación lenta de forma generalizada.

Antes de cambiar nada: el camino de vuelta

El diagnóstico de los dos apartados siguientes es de solo lectura. El riesgo empieza donde tocas configuraciones, y eso puede parar el servicio por tres vías: una configuración de nginx defectuosa impide que arranque el servidor web, un archivo de pool defectuoso impide que arranque PHP-FPM, y unos límites subidos con demasiada generosidad pueden agotar la RAM. El último caso es el más desagradable, porque entonces el kernel mata procesos y no tiene por qué tocarle al culpable. Si le toca al servicio SSH, el servidor deja de poder manejarse por red.

Por eso, haz primero copias, por debajo de /root y nunca en el directorio web. La marca de tiempo en el nombre es importante, porque rara vez se interviene una sola vez y cp -a sobrescribe sin decir nada una copia que ya exista:

mkdir -p /root/backups
cp -a /etc/nginx/nginx.conf /root/backups/nginx.conf.$(date +%F-%H%M)
cp -a /etc/nginx/sites-available/example.com /root/backups/example.com.$(date +%F-%H%M)
cp -a /etc/php/8.4/fpm/php.ini /root/backups/php.ini.$(date +%F-%H%M)
cp -a /etc/php/8.4/fpm/pool.d/www.conf /root/backups/www.conf.$(date +%F-%H%M)

El camino de vuelta son tres líneas, y el orden es deliberado:

cp -a /root/backups/example.com.2026-09-03-1030 /etc/nginx/sites-available/example.com
nginx -t
systemctl reload nginx

Usa reload en lugar de restart mientras puedas. reload solo adopta la nueva configuración si está libre de errores. Un restart termina primero el proceso en marcha y, si hay un fallo, te deja sin servidor web.

Si el servidor deja de responder por completo, en los servidores root KVM y en los servidores dedicados de KernelHost tienes la consola VNC en el área de cliente. Cuelga de la capa de virtualización o de la propia conexión, no del stack de red del sistema invitado, así que sigue funcionando aunque ya no haya ningún servicio accesible. Entra ahí una vez antes de empezar y asegúrate de conocer la contraseña de root. Comando de comprobación después de cada intervención:

systemctl is-active nginx php8.4-fpm
free -m

La línea del log de errores que decide el caso

Un 504 siempre deja rastro:

2026/09/03 10:12:33 [error] 812#812: *5 upstream timed out (110: Connection timed out)
while reading response header from upstream, client: 203.0.113.7, server: example.com,
request: "GET /report.php HTTP/1.1", upstream: "fastcgi://unix:/run/php/php8.4-fpm.sock:"

Lo decisivo no es el número de error 110, que es el mismo en todos los 504, sino la fase que viene detrás:

• while connecting to upstream: el establecimiento de la conexión no llegó a producirse. Con un backend remoto es casi siempre un filtro de paquetes que descarta los paquetes en vez de rechazarlos, porque un rechazo volvería de inmediato y daría un 502.
• while sending request to upstream: nginx no consiguió soltar el cuerpo de la petición, algo típico en subidas grandes.
• while reading response header from upstream: el caso normal. El backend lo ha recibido todo y sigue calculando sin enviar siquiera la primera línea de cabecera.
• while reading upstream: las cabeceras llegaron y después se atascó el cuerpo. Esto se ve en respuestas por streaming y en exportaciones.

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

Muchos hosts virtuales escriben en un log de errores propio. Dónde está ese archivo y por qué al buscar en sites-enabled hace falta la -R mayúscula lo explica el artículo sobre el 502. Si la búsqueda se queda vacía aunque el navegador muestre un 504, el error no viene de este nginx.

Dónde se consume el tiempo: medir en vez de adivinar

nginx puede registrar en cada petición cuánto ha tardado el backend. Es el paso más importante del diagnóstico, porque responde a la pregunta "¿aplicación o línea?" sin necesidad de suponer nada. En el bloque http de /etc/nginx/nginx.conf:

log_format kh_timing '$time_iso8601 $status rt=$request_time '
                     'uct=$upstream_connect_time uht=$upstream_header_time '
                     'urt=$upstream_response_time "$request"';

En el bloque server afectado, una segunda línea de log. El log de acceso que ya existe se queda intacto, nginx escribe los dos:

access_log /var/log/nginx/timing.log kh_timing;

nginx -t
systemctl reload nginx
tail -n 5 /var/log/nginx/timing.log

Después de unos minutos de funcionamiento, saca arriba las peticiones más lentas:

awk '{ t=$3; sub(/^rt=/, "", t); print t, $0 }' /var/log/nginx/timing.log | sort -rn | head -20

Dos detalles ahorran mucho tiempo. Varios valores separados por coma dentro de un mismo campo significan que la petición fue a más de un destino, es decir, que hubo un reintento. Y la pista más contundente de todas: si la duración medida coincide al segundo con el valor configurado, por ejemplo 60,001 segundos con un plazo de 60, entonces ha saltado el plazo y el backend no se ha rendido por su cuenta. Valores irregulares como 43,7 segundos indican que lo que frenó fue otra cosa.

Qué plazo se aplica realmente

nginx tiene más de una docena de directivas para los timeouts, y la hora perdida más habitual nace de tocar la que no es. Cuál se aplica depende de qué módulo procesa el bloque location.

El plazo cuenta entre dos lecturas, no para la respuesta completa. Una descarga que dura diez minutos y que va entregando datos sin interrupción llega hasta el final. Un backend que se calla durante 61 segundos queda fuera. Por eso, en exportaciones que se atascan suele ayudar más hacer que la aplicación emita algo con regularidad que subir el plazo.

send_timeout no hace nada contra un 504. Ese plazo afecta a la transmisión hacia el visitante. Si vence, no hay página de error, sino una descarga cortada. Solo pasa a ser relevante cuando desactivas el búfer intermedio con proxy_buffering off;, porque entonces un visitante lento frena hasta el backend.

nginx también acepta directivas que no tienen ningún efecto en el bloque donde están. Un proxy_read_timeout 300s; dentro de un bloque PHP con fastcgi_pass es sintácticamente impecable, nginx -t informa syntax is ok y la página sigue cortándose a los 60 segundos. Al revés, exactamente igual. Es la causa más frecuente de que un plazo ampliado no sirva de nada. Lo que se aplica de verdad lo enseña la configuración ensamblada:

nginx -T | grep -E "read_timeout|send_timeout|fastcgi_pass|proxy_pass"

Si una ruta concreta tiene que correr más tiempo de verdad, pon el plazo exactamente ahí y en ningún otro sitio. El signo de igual lo convierte en una coincidencia exacta, y esa gana frente al bloque general location ~ \.php$, que procesa el resto de los archivos PHP:

location = /admin/export.php {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.4-fpm.sock;
    fastcgi_read_timeout 300s;
}

nginx -t
systemctl reload nginx
curl -s -o /dev/null -w "%{http_code} %{time_total}\n" -H "Host: example.com" http://127.0.0.1/admin/export.php

PHP: por qué max_execution_time rara vez se aplica aquí

La suposición más inmediata es que PHP termina por sí solo un script colgado. En este caso concreto, casi nunca es así. Primero, la trampa de medición: php -i consulta la variante de línea de comandos. Esa usa una configuración propia bajo /etc/php/8.4/cli/ y de todas formas corre sin límite de tiempo de ejecución, así que no dice nada sobre FPM. Lo que cuenta son estos dos sitios:

grep -n "^max_execution_time" /etc/php/8.4/fpm/php.ini
grep -rn "max_execution_time" /etc/php/8.4/fpm/pool.d/

En el archivo de pool, el valor puede estar sobrescrito con php_value[max_execution_time] o con php_admin_value[max_execution_time]. Un valor puesto con php_admin_value ya no se puede cambiar desde la aplicación mediante ini_set(). Si tu framework sube el tiempo de ejecución por su cuenta y de repente eso no surte efecto, la razón es esa.

Y ahora, el punto que de verdad importa: en Linux, el tiempo de espera dentro de las llamadas al sistema no cuenta. El reloj solo corre mientras el propio script calcula. Si espera a una consulta de base de datos, a una API externa o al sistema de archivos, el reloj se para. Con eso, un script puede quedarse pegado diez minutos a una consulta colgada sin que el límite de tiempo de ejecución salte nunca. Quien lo termina entonces es el plazo de nginx, y el resultado es el 504.

De ahí sale una regla incómoda: max_execution_time protege frente a bucles infinitos en tu propio código, no frente a la espera. El único límite duro del lado de PHP es request_terminate_timeout en el archivo de pool, que se lleva por delante el proceso de trabajo sin importar de qué esté colgado. Eso sí, produce un 502 y no un 504. Ordena los plazos de dentro hacia fuera de forma creciente, para que actúe primero la capa que todavía puede generar un mensaje comprensible. Con los scripts que calculan funciona; con los que esperan no, por el motivo que acabamos de ver. Ahí solo queda limitar la propia espera.

Por qué subir el plazo suele ser la respuesta equivocada

Echa la cuenta un momento. Un pool con pm.max_children = 10 tiene diez procesos de trabajo. Una página necesita 90 segundos. Diez llamadas simultáneas ocupan así cada uno de ellos durante minuto y medio. En ese tiempo, nadie recibe ya ninguna página PHP, tampoco la portada. Una subpágina lenta se ha convertido en una caída. Hay tres mecanismos que lo agravan:

• El visitante recarga. Eso genera una petición adicional, pero no libera la anterior. PHP no se entera de que un visitante ha cortado hasta que el script vuelve a emitir algo, y un script que está calculando no emite nada durante mucho rato.
• nginx reintenta por su cuenta. En un bloque upstream con varios destinos, proxy_next_upstream viene de fábrica en error timeout. Una petición que ha vencido se va al siguiente servidor y la consulta cara se ejecuta una segunda vez. Las peticiones de escritura quedan excluidas, las de lectura no. Se desactiva con proxy_next_upstream error;.
• La monitorización también repite. Un intervalo de comprobación de 60 segundos sobre una página que necesita 90 genera una carga permanente que nunca llega a despacharse.

A eso se suma que nadie espera cinco minutos por una página web. Un plazo de 300 segundos convierte un problema de un minuto en uno de cinco, y el visitante hace rato que se ha ido mientras el proceso de trabajo sigue calculando.

Hasta qué punto está realmente saturado lo enseña la página de estado de PHP-FPM. Pon pm.status_path = /fpm-status en el archivo de pool y crea en el bloque server un acceso alcanzable solo en local:

location = /fpm-status {
    allow 127.0.0.1;
    deny all;
    include fastcgi_params;
    fastcgi_pass unix:/run/php/php8.4-fpm.sock;
}

systemctl reload php8.4-fpm
nginx -t
systemctl reload nginx
curl -s -H "Host: example.com" http://127.0.0.1/fpm-status

Fíjate en active processes, listen queue y max active processes. Si listen queue se queda de forma permanente por encima de cero, el número de procesos de trabajo no da abasto para el tiempo de ejecución actual de las páginas. Ese es el momento en el que hay que bajar el tiempo de ejecución, no subir el plazo.

Los tres devoradores de tiempo habituales

Base de datos

En la mayoría de los casos, el tiempo está aquí. Mira primero qué se está ejecutando en ese momento. En los cuatro sistemas, el acceso de root funciona de fábrica a través del socket Unix, así que el comando no necesita contraseña:

mysql -e "SHOW FULL PROCESSLIST;"

Interesan las columnas Time y State. Valores como Sending data o Waiting for table metadata lock con segundos de dos cifras son tu caso. Para buscar de forma sistemática está el log de consultas lentas, que se puede activar en caliente:

mysql -e "SET GLOBAL slow_query_log = 1; SET GLOBAL long_query_time = 1;"
mysql -e "SHOW VARIABLES LIKE 'slow_query_log_file';"

El nombre del archivo lo sacas de la segunda salida, porque cambia de un sistema a otro: Debian apuesta normalmente por MariaDB y escribe en /var/log/mysql/mariadb-slow.log, mientras que en Ubuntu el archivo se llama de otra forma según el servidor instalado. Evalúalo después de unos minutos y vuelve a desactivarlo, porque el log cuesta carga de escritura:

mysqldumpslow -s t /var/log/mysql/mariadb-slow.log | head -30
mysql -e "SET GLOBAL slow_query_log = 0;"

El modificador -s t ordena por tiempo total. La consulta más cara la revisas con EXPLAIN: casi siempre falta un índice justo en la columna por la que se filtra o se ordena. SET GLOBAL surte efecto de inmediato, pero no sobrevive a un reinicio de la base de datos. Del lado de la base de datos también hay un límite superior por consulta: MariaDB tiene max_statement_time en segundos y MySQL max_execution_time en milisegundos, esto último solo para consultas de lectura. Con eso, tu aplicación recibe un error limpio en lugar de un proceso de trabajo ocupado.

APIs externas

Si tu página consulta en cada llamada a un proveedor de pagos o a un servidor de licencias, la avería de ellos se convierte en tu 504. Mide esa llamada por separado, desde el servidor:

curl -o /dev/null -s -w "dns=%{time_namelookup} connect=%{time_connect} ttfb=%{time_starttransfer} total=%{time_total}\n" https://api.example.com/status

Si ya llama la atención dns, la culpa es de la resolución de nombres y no del otro extremo; contraprueba con time getent hosts api.example.com. En el código, cada llamada externa necesita un plazo propio y corto: en cURL son CURLOPT_CONNECTTIMEOUT y CURLOPT_TIMEOUT. Si en su lugar aplicas file_get_contents() sobre una dirección, acabas en default_socket_timeout del php.ini, donde de fábrica hay 60 segundos:

grep -n "default_socket_timeout" /etc/php/8.4/fpm/php.ini

La regla general: la suma de todos los plazos externos de una petición tiene que quedar por debajo de fastcgi_read_timeout. Si no, nginx corta antes de que tu código pueda mostrar una página de error comprensible.

Sistema de archivos y RAM

Un disco lleno hace que las escrituras vayan lentas o resulten imposibles, y eso afecta a la vez a los archivos de sesión, a la caché y a los logs. Comprueba las dos cosas, el espacio en disco y los inodos:

df -h
df -i

El segundo comando es el que se olvida a menudo. Una partición puede estar al 40 % de ocupación y aun así no admitir ni un archivo más si los inodos se han agotado. El segundo candidato es la falta de memoria: si el sistema empieza a tirar de swap, cada petición se vuelve lenta sin que la culpa sea de ninguna consulta concreta.

vmstat 1 5

Si las columnas si y so se mantienen permanentemente por encima de cero, el kernel está paginando sin parar hacia dentro y hacia fuera, y lo que tienes es un problema de memoria y no de tiempo. Cómo tratar eso bien lo explica configurar swap y evitar el Out-of-Memory. El tercer candidato son las unidades de red: un punto de montaje NFS colgado bloquea cualquier proceso que lo toque, y ahí entra también tu comando de diagnóstico. Por eso, ponle un plazo delante:

timeout 5 df -h

Las tareas largas no pintan nada dentro de la petición

Hay tareas que sencillamente tardan: un informe anual, una importación de 200.000 filas, una conversión de imágenes. El fallo no está en que tarden mucho, sino en que un servidor web se quede esperándolas. La forma limpia tiene tres partes:

1. La petición crea un trabajo, en una tabla o en una cola, y responde de inmediato. El código de estado que corresponde es el 202, junto con una dirección desde la que se puede consultar el estado.
2. Un proceso de trabajo fuera de nginx recoge esos trabajos y los resuelve. No tiene ningún plazo pisándole los talones, porque nadie lo está esperando.
3. La interfaz consulta el estado. Esa consulta es siempre rápida, dure lo que dure la tarea.

El proceso de trabajo lo ejecutas como servicio propio, para que vuelva por sí solo después de una caída y después de un reinicio. Qué aspecto tiene una unit así lo enseña crear un servicio systemd. Para tareas a intervalos fijos basta con un cronjob, y ahí necesitas un bloqueo para que dos ejecuciones no se adelanten la una a la otra. Con -n, la segunda ejecución aborta al momento en lugar de esperar:

flock -n /run/lock/kh-worker.lock /usr/bin/php /var/www/html/worker.php

Para los frameworks habituales, la cola ya viene hecha y solo hay que ponerla en marcha: en Laravel php artisan queue:work, en Symfony php bin/console messenger:consume con el nombre de tu transporte. Las dos cosas van en una unit de systemd, no en una ventana de terminal.

Un caso especial merece una mención expresa: WordPress lanza de fábrica las tareas programadas dentro de las peticiones de los visitantes. Es decir, un visitante paga con su tiempo de espera que por detrás se esté ejecutando una comprobación de actualizaciones. La línea define('DISABLE_WP_CRON', true); en wp-config.php, por encima de la referencia a wp-settings.php, lo desactiva. Después, las tareas pendientes las lanzas tú mismo con regularidad:

wp cron event run --due-now --path=/var/www/html

Lo que tenga que seguir siendo síncrono por fuerza recibe un bloque location propio con su propio plazo y, además, un límite para que esa única ruta no ocupe todos los procesos de trabajo: limit_conn_zone $binary_remote_addr zone=export:10m; en el bloque http y limit_conn export 1; en el bloque correspondiente. Los intentos adicionales reciben entonces un 503 en lugar de un servidor ocupado.

Errores frecuentes y soluciones

Cómo saber que está resuelto

Un comando sin mensaje de error no demuestra nada, y una sola llamada con éxito tampoco. Cuatro pruebas que, juntas, sí sostienen:

1. Código de estado y duración directamente en el servidor, para que ninguna caché maquille el resultado. Se espera un 200 y una duración claramente por debajo del plazo. Un 200 a los 58 segundos con un plazo de 60 no es un éxito, sino la próxima caída en cuanto suba algo la carga. Y aquí cuenta la peor de veinte llamadas:

   for i in $(seq 1 20); do curl -s -o /dev/null -w "%{http_code} %{time_total}\n" -H "Host: example.com" http://127.0.0.1/report.php; done | sort -k2 -n | tail -3

2. El log de errores se queda callado. Vacíalo antes de la prueba con truncate -s 0 /var/log/nginx/error.log, lanza las llamadas y vuelve a mirar dentro. Un archivo vacío es la prueba de verdad.
3. La cola de PHP-FPM está a cero. Mientras en la página de estado haya algo esperando bajo listen queue, la causa solo se ha desplazado.
4. Un reinicio no cambia nada. El punto que más se salta la gente. Los valores puestos con SET GLOBAL, los procesos arrancados a mano y los directorios creados por ti mismo bajo /run no lo sobreviven. Comprueba systemctl is-enabled nginx php8.4-fpm y reinicia el servidor una vez de forma controlada, mientras todavía estás delante mirando.

Ese reinicio, con acceso a consola incluido, lo haces en los servidores root KVM y en los servidores dedicados de KernelHost desde el área de cliente, incluso cuando el servicio web ya no entrega nada. Los servidores están en el centro de datos maincubes de Frankfurt am Main (certificado TÜV TIER3+), con filtrado previo en la red que tienen por delante.

Lista de comprobación rápida para la emergencia

1. Contar los códigos de estado en el log de acceso. El 504, el 499 y el 502 juntos dicen más que cualquiera de ellos por separado.
2. grep "upstream timed out" /var/log/nginx/error.log y anotar la fase que aparece en el mensaje.
3. Activar el log de tiempos y comparar uct, uht y urt. Si la duración encaja al segundo con el plazo configurado, es que ha saltado el plazo.
4. Determinar el devorador de tiempo: base de datos, API externa, sistema de archivos o memoria.
5. Comprobar con nginx -T qué plazo se aplica en ese bloque antes de cambiar ninguno.
6. Solo después decidir: arreglarlo, moverlo a una cola o, como última opción, subir el plazo solo para esa única ruta.
7. Después del arreglo: vaciar el log, medir veinte llamadas y reiniciar el servidor una vez de forma controlada.