Resolver Error 504 Gateway Timeout en Nginx

Seguro que te suena la situación: estás trabajando en tu web, todo va como la seda, y de repente, ¡zas! Pantalla en blanco y un mensaje que te hiela la sangre: 504 Gateway Timeout. Si has llegado hasta aquí, es probable que tu servidor web sea Nginx y que este error te esté quitando el sueño.

¡Que no cunda el pánico! En este artículo, actualizado para 2025, vamos a desglosar qué significa este error, por qué aparece y, lo más importante, cómo puedes solucionarlo. Y te lo explicaré de una forma sencilla, para que no necesites ser un administrador de sistemas con 20 años de experiencia para entenderlo. ¡Vamos al lío!

¿Qué es exactamente un error 504 Gateway Timeout?

Imagina que Nginx es el camarero de un restaurante muy eficiente. Tú, el cliente, le pides un plato (accedes a una URL). El camarero (Nginx) va a la cocina (el backend de tu aplicación, como PHP-FPM, Node.js, Python…) y le pasa la comanda.

El problema viene cuando la cocina tarda demasiado en preparar el plato. El camarero tiene una paciencia limitada; no puede esperar eternamente. Si la cocina no saca el plato a tiempo, el camarero vuelve a tu mesa y te dice: «Lo siento, ha habido un problema de tiempo de espera en la cocina».

Eso es, en esencia, un error 504 Gateway Timeout. Nginx, actuando como un gateway o proxy inverso, ha esperado una respuesta del proceso que está detrás (el backend), pero este no ha respondido en el tiempo estipulado. Es importante entender que el problema no es de Nginx en sí mismo, sino de la comunicación con lo que hay detrás o del propio backend que está sobrecargado o es demasiado lento.

Causas más comunes del dichoso error 504

Antes de tocar nada, es fundamental entender por qué puede estar pasando esto. Las causas más habituales son:

Scripts que tardan una eternidad: Tienes un proceso en tu aplicación (un script PHP, por ejemplo) que realiza una tarea muy pesada. Puede ser una consulta a la base de datos muy compleja, la importación de un archivo enorme, la generación de un informe o la comunicación con una API externa que está lenta.
El backend está sobrecargado o «muerto»: El servicio que ejecuta tu aplicación (normalmente PHP-FPM si usas WordPress, Laravel, etc.) está saturado. Puede que no tenga suficientes «trabajadores» (workers) para atender todas las peticiones o que el servidor se haya quedado sin CPU o memoria RAM.
La configuración de timeout de Nginx es demasiado estricta: A veces, el camarero es simplemente muy impaciente. Nginx tiene unos tiempos de espera por defecto que, para ciertas tareas, pueden ser demasiado cortos.
Problemas de red o firewall: Si Nginx y tu aplicación están en servidores diferentes, un firewall podría estar bloqueando la conexión o puede haber problemas de red entre ellos.

La guía paso a paso para Resolver Error 504 Gateway Timeout en Nginx

Ahora que ya tenemos una idea de las posibles causas, vamos a la acción. Sigue estos pasos de forma ordenada para resolver el error 504 Gateway Timeout en Nginx.

Paso 1: Aumentar los valores de timeout en Nginx

Esta es la solución más rápida y común. Vamos a darle un poco más de paciencia a nuestro «camarero». Para ello, necesitas editar tu fichero de configuración de Nginx. Este suele estar en /etc/nginx/nginx.conf o en un fichero específico para tu sitio dentro de /etc/nginx/sites-available/.

Busca el bloque http o, si es específico para un sitio, el bloque server o location. Añade o modifica las siguientes directivas:

«`nginx
http {
# … otras configuraciones …

proxy_connect_timeout 600s;
proxy_send_timeout 600s;
proxy_read_timeout 600s;
fastcgi_send_timeout 600s;
fastcgi_read_timeout 600s;

}
«`

¿Qué significa cada una?

proxy_..._timeout: Se usan cuando Nginx actúa como proxy inverso para otro servidor web (como Apache) o una aplicación (Node.js, Python…). proxy_read_timeout es la más importante aquí, ya que define cuánto tiempo esperará Nginx a que el backend envíe una respuesta. Puedes encontrar más detalles en la documentación oficial de Nginx sobre el módulo proxy.
fastcgi_..._timeout: Son cruciales si usas PHP-FPM. fastcgi_read_timeout es el equivalente a proxy_read_timeout pero para FastCGI, el protocolo que Nginx usa para hablar con PHP.

He puesto 600s (600 segundos o 10 minutos) como un valor alto para asegurarnos de que el problema no viene de aquí. Puedes ajustarlo a un valor más razonable una vez soluciones el problema de fondo.

Importante: Después de guardar los cambios, no te olvides de recargar la configuración de Nginx para que los aplique:

bash sudo systemctl reload nginx

Paso 2: Ajustar la configuración de PHP (PHP-FPM)

Si has aumentado el tiempo de espera de Nginx pero el error persiste, es muy probable que el problema esté en la «cocina». Aunque Nginx espere 10 minutos, si PHP tiene configurado un límite de ejecución de 30 segundos, el script morirá mucho antes y Nginx recibirá una conexión cerrada, lo que puede derivar en un 504.

Hay dos sitios principales donde mirar:

El fichero php.ini: Busca la directiva max_execution_time. Este valor define el tiempo máximo en segundos que un script puede tardar en ejecutarse.
- Localiza tu php.ini (la ubicación varía, pero puedes usar php --ini para encontrarla).
- Aumenta el valor: max_execution_time = 300 (5 minutos).
- Puedes consultar la documentación oficial de PHP sobre esta directiva para más información.
La configuración del pool de PHP-FPM: A menudo, esta configuración anula lo que ponga en php.ini. El fichero suele estar en /etc/php/[tu_version]/fpm/pool.d/www.conf. Busca la directiva request_terminate_timeout.
- Si está definida y tiene un valor bajo, auméntala. Este valor indica el tiempo tras el cual se da por finalizada una petición. Si pones 0, se desactiva el límite y se usará el max_execution_time de php.ini.
- request_terminate_timeout = 300

Después de cambiar cualquiera de estos valores, recuerda reiniciar el servicio de PHP-FPM:

bash sudo systemctl restart php8.3-fpm # Cambia "8.3" por tu versión de PHP

Paso 3: Optimizar es la verdadera solución a largo plazo

Aumentar los timeouts es como poner un parche. Funciona, pero si tus scripts son lentos, el problema de fondo sigue ahí. Tu web será lenta para los usuarios y consumirá más recursos del servidor. La verdadera solución para resolver el error 504 Gateway Timeout en Nginx de forma definitiva es optimizar.

Optimiza las consultas a la base de datos: Una consulta lenta es una de las causas más frecuentes. Usa herramientas como EXPLAIN en SQL para analizar tus queries y asegúrate de que estás usando índices en las columnas por las que buscas o filtras.
Utiliza caché: Si una página genera contenido que no cambia a menudo, ¿por qué generarlo cada vez? Usa sistemas de caché (Redis, Memcached, o incluso plugins de caché para WordPress) para servir una versión estática y ultrarrápida.
Mueve las tareas pesadas a segundo plano: Si un usuario solicita una acción que tarda mucho (ej: exportar un informe de ventas de todo el año), no le hagas esperar. Utiliza colas de trabajos (background jobs). La petición del usuario simplemente añade la tarea a una cola, y un proceso en segundo plano la ejecuta. Cuando esté lista, se le puede notificar al usuario. Esto libera al proceso principal y mejora drásticamente la experiencia de usuario.

Paso 4: Revisa los recursos del servidor y los logs

Si todo lo demás falla, es hora de investigar más a fondo.

Revisa el consumo de CPU y RAM: Usa comandos como top o htop en tu terminal. Si ves que la CPU está al 100% o que la memoria RAM está casi agotada, es probable que tu servidor no tenga suficientes recursos. Quizás sea el momento de optimizar más o de ampliar tu plan de hosting.
¡Mira los logs!: Los archivos de registro son tus mejores amigos.
- Log de errores de Nginx: /var/log/nginx/error.log
- Log de errores de PHP-FPM: La ubicación varía, pero suele estar en /var/log/php8.3-fpm.log (cambia la versión).
- Busca en los logs mensajes que coincidan con la hora en que se produjo el error 504. A menudo encontrarás pistas muy valiosas, como «PHP-FPM process timed out» o «upstream timed out».

Conclusión: Mantén la calma y sigue los pasos

El error 504 Gateway Timeout puede parecer intimidante, pero como has visto, casi siempre se reduce a un desajuste de tiempos de espera o a un cuello de botella en el rendimiento de tu aplicación.

El enfoque correcto es ir de lo más sencillo a lo más complejo. Empieza aumentando los timeouts en Nginx y PHP-FPM para ver si eso soluciona el problema de inmediato. Si lo hace, ¡genial! Pero no te quedes ahí. Investiga qué proceso está tardando tanto y optimízalo. Esa es la clave para tener una web robusta, rápida y libre de errores.

Así que la próxima vez que te encuentres con este error, respira hondo, vuelve a esta guía y empieza a investigar. ¡Seguro que das con la tecla

Javierin.com