Error 504 Gateway Time-out en Nginx: Guía de Solución

📅 Publicado el 10 de septiembre, 2026 · Por Equipo RedServicio

¿Qué es el error 504 Gateway Time-out?

El error 504 Gateway Time-out aparece muchísimo cuando combinamos Nginx como servidor web con PHP-FPM de procesador. ¿Qué significa en la práctica? Que Nginx, que actúa de intermediario, le pasó una petición a PHP-FPM y este no contestó dentro del plazo. El visitante de tu web, mientras tanto, se encuentra con una página en blanco o con el maldito mensaje «504 Gateway Time-out» en vez de tu contenido.

Conviene distinguirlo del 502 (Bad Gateway). Ese indica que PHP-FPM no responde en absoluto; el 504 dice que responde, pero tarde. Demasiado tarde. Y eso casi siempre apunta a procesos lentos: scripts pesados, consultas a base de datos eternas o límites de tiempo mal configurados.

Causas más comunes del error 504 en Nginx y PHP-FPM

Antes de ponerse a tocar configuración a lo loco, mejor localizar el origen. Lo habitual suele ser una de estas cosas:

• Timeouts de Nginx demasiado bajos: por defecto, Nginx espera solo 60 segundos la respuesta del backend.
• Scripts PHP muy lentos: importaciones, generación de informes, backups… procesos que se pasan del tiempo de ejecución.
• Consultas a la base de datos bloqueadas: una consulta MySQL sin índices puede tumbar el tiempo de respuesta entero.
• Saturación de workers de PHP-FPM: si todos los procesos hijos están ocupados, las peticiones se encolan y acaban superando el límite.
• Recursos del servidor justos: poca RAM o CPU, y todo se arrastras.

Solución 1: Aumentar los timeouts en Nginx

Empecemos por lo básico. Ajusta las directivas de tiempo de espera en el bloque server o location de tu configuración de Nginx (por ejemplo en /etc/nginx/conf.d/tu-sitio.conf):

¿Cuál de las tres directivas importa más?

• fastcgi_read_timeout: cuánto espera Nginx entre dos lecturas de respuesta de PHP-FPM. Es la que de verdad afecta al error 504.
• fastcgi_connect_timeout: el tiempo para establecer la conexión con PHP-FPM.
• fastcgi_send_timeout: máximo para enviar la petición a PHP-FPM.

Guardas, verificas la sintaxis y recargas:

Solución 2: Ajustar PHP-FPM y php.ini

Ojo con esto: subir el timeout de Nginx no sirve de nada si PHP corta antes la ejecución. Edita tu php.ini (normalmente está en /etc/php/8.2/fpm/php.ini) y repasa estos valores:

• max_execution_time = 300: segundos máximos que un script puede correr.
• max_input_time = 300: tiempo máximo para procesar los datos de entrada.
• memory_limit = 256M: memoria por proceso. Poca memoria también ralentiza, no lo olvides.

Después reinicia el servicio: systemctl restart php8.2-fpm (cambia la versión según la que uses). Para casos puntuales, como una importación pesada, también puedes meter set_time_limit(300) al inicio del script en cuestión.

Revisar la configuración del pool de PHP-FPM

En /etc/php/8.2/fpm/pool.d/www.conf, mira estos parámetros:

• pm.max_children: procesos simultáneos máximo. Si se queda corto, las peticiones se encolan y aparecen los timeouts.
• pm.start_servers y pm.max_spare_servers: cuántos procesos quedan listos en cada momento.

Una regla práctica que funciona bastante bien: con 2 GB de RAM y procesos de ~50 MB, pm.max_children ronda los 30-40. Y si activas request_slowlog_timeout, el log de PHP-FPM (/var/log/php-fpm/www-slow.log) te dirá exactamente qué scripts van lentos.

Solución 3: Optimizar la base de datos

¿El 504 solo aparece en páginas concretas? Entonces casi seguro que la culpa es de consultas lentas. Activa el slow query log de MySQL o MariaDB:

Con eso registrarás cualquier consulta que tarde más de 2 segundos. Desde ahí: añade índices a las columnas consultadas con frecuencia, usa caché de consultas u objetos (Redis va de lujo para esto) y evita meter consultas dentro de bucles en tu PHP. Sí, eso que todos hemos hecho alguna vez.

Solución 4: Implementar caché para evitar timeouts

A largo plazo, la mejor jugada es que las peticiones lentas ni lleguen a PHP-FPM:

1. FastCGI cache en Nginx: guarda en caché las respuestas de PHP y sirve páginas casi instantáneamente.
2. Page cache a nivel de aplicación: plugins como W3 Total Cache (WordPress) o caché propia en tus aplicaciones.
3. OPcache: viene activado en las versiones modernas de PHP y acelera la ejecución de scripts entre un 50% y un 70%.

Con la caché bien configurada, la mayoría de visitantes reciben respuestas en milisegundos. Solo los procesos administrativos pesados quedan expuestos al timeout.

Cómo diagnosticar el error 504 paso a paso

1. Mira los logs de Nginx: tail -f /var/log/nginx/error.log. Busca mensajes tipo «upstream timed out».
2. Revisa los de PHP-FPM: /var/log/php8.2-fpm.log, atento a la saturación de workers.
3. Distingue si el error es general o solo en páginas específicas. Eso delata scripts concretos.
4. Monitoriza recursos con htop o iotop mientras reproduces el error.
5. Aplica las correcciones de timeout y optimización según lo que encuentres.

Conclusión

El error 504 Gateway Time-out en Nginx con PHP-FPM no suele tener un único culpable. Se arregla combinando tres frentes: subir bien los timeouts de Nginx y PHP, dimensionar el pool de PHP-FPM según los recursos reales de tu servidor, y optimizar las consultas a base de datos. Una capa de caché encima convierte la solución en algo definitivo, y de paso tu web va más rápida para todos.

¿Prefieres no pelearte con esto? En RedServicio.net ofrecemos hosting de calidad con soporte técnico 24/7: nuestros expertos pueden revisar y optimizar la configuración de tu servidor para que el 504 no vuelva a molestar. Y si gestionas tu propio VPS, sigue esta guía paso a paso y vigila los logs. Por experiencia, te lo digo: los problemas avisan antes de reventar. Solo hay que estar mirando.