Error 504 Gateway Timeout en Nginx y PHP-FPM: Solución

Qué significa el error 504 Gateway Timeout

El error 504 Gateway Timeout aparece cuando Nginx actúa como proxy o servidor frontend y no recibe respuesta del backend (normalmente PHP-FPM) dentro del tiempo límite que tiene configurado. En la práctica: el visitante ve una página en blanco o el típico mensaje «504 Gateway Time-out» mientras tu aplicación sigue ejecutándose en segundo plano. O quizá se ha quedado bloqueada, que también pasa.

Aclaremos algo primero: no es problema del navegador del usuario ni de su conexión. La causa está en tu servidor, siempre. Y la buena noticia es que, con los ajustes correctos, en la mayoría de los casos se arregla en minutos.

Causas más habituales del error 504 en Nginx con PHP-FPM

Antes de ponerse a tocar configuración, conviene saber de dónde viene el problema. Las causas más frecuentes que me encuentro son estas:

• Timeouts demasiado cortos: los valores por defecto de Nginx (60 segundos) y PHP-FPM no dan de sí para procesos largos. Importaciones, backups, llamadas a APIs lentas…
• Scripts PHP saturados: plugins pesados en WordPress, bucles mal optimizados, consultas a base de datos sin índices.
• Falta de workers en PHP-FPM: si todos los procesos hijos están ocupados, las peticiones nuevas quedan en cola hasta agotar el timeout.
• Problemas en el upstream: el servicio PHP-FPM está caído, escucha en un socket distinto al configurado o el socket Unix tiene permisos incorrectos.
• Recursos agotados: memoria que no llega, CPU al 100 por ciento, límites de memoria de PHP demasiado bajos.

Solución 1: Ajustar los timeouts en Nginx

Primer paso: ampliar los tiempos de espera en el bloque server o en la directiva location que pasa las peticiones a PHP-FPM. Abre tu archivo de configuración (suele estar en /etc/nginx/sites-available/tudominio.conf o en /etc/nginx/conf.d/default.conf) y añade o modifica estas directivas dentro del bloque location ~ \.php$:

fastcgi_read_timeout 300;
fastcgi_connect_timeout 60;
fastcgi_send_timeout 300;

Si usas Nginx como proxy inverso hacia otro backend, aplica también:

proxy_read_timeout 300;
proxy_connect_timeout 60;
proxy_send_timeout 300;

Verifica la sintaxis y recarga:

nginx -t && systemctl reload nginx

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

Aquí hay un detalle que mucha gente pasa por alto: puedes poner Nginx a esperar 300 segundos, pero si PHP corta la ejecución antes, el 504 sigue ahí. Hay que revisar ambos lados.

En el archivo php.ini

Localiza el php.ini activo (con php –ini o un phpinfo lo sacas enseguida) y ajusta:

• max_execution_time = 300
• max_input_time = 300
• memory_limit = 256M (o más, según lo que pida tu aplicación)

En la configuración del pool de PHP-FPM

Edita el pool, habitualmente /etc/php/8.1/fpm/pool.d/www.conf (ajusta la versión a la tuya), y revisa esta línea:

request_terminate_timeout = 300

Este valor anula max_execution_time en PHP-FPM y debe coincidir con el fastcgi_read_timeout de Nginx. Luego reinicia el servicio:

systemctl restart php8.1-fpm

Solución 3: Comprobar la capacidad del pool de PHP-FPM

¿El error aparece sobre todo cuando hay carga? Entonces probablemente se te quedan cortos los procesos hijos. Mira los valores pm.max_children, pm.start_servers y pm.max_spare_servers en el pool. Como referencia, para un servidor con 4 GB de RAM dedicados a PHP:

• pm = dynamic
• pm.max_children = 20
• pm.start_servers = 5
• pm.min_spare_servers = 3
• pm.max_spare_servers = 10

El cálculo de max_children es sencillo: memoria disponible dividida entre el consumo medio de un proceso PHP (con WordPress suele rondar los 50-120 MB). Y consulta el log de PHP-FPM en /var/log/php-fpm/www-error.log o /var/log/php8.1-fpm.log. Si ves avisos de «server reached pm.max_children», necesitas más procesos… o mejor código.

Solución 4: Diagnosticar scripts lentos y cuellos de botella

Seamos honestos: subir los timeouts es un parche. La solución de verdad pasa por identificar qué proceso tarda tanto. Para eso:

• slowlog de PHP-FPM: activa request_slowlog_timeout = 5s y slowlog = /var/log/php-fpm/slow.log. Registrará cualquier script que tarde más de 5 segundos, con su traza completa.
• Logs de Nginx: revisa /var/log/nginx/error.log, donde verás entradas como «upstream timed out (110: Connection timed out) while reading response header».
• Monitorización de MySQL: activa el slow query log de MariaDB/MySQL. Las consultas sin índices son, por experiencia, la causa número uno de timeouts en WordPress.
• htop y iostat: para descartar saturación de CPU o de disco en el momento del error.

El error 504 en WordPress: casos específicos

En WordPress este error suele aparecer durante importaciones de contenido, actualizaciones de plugins pesados, generación de backups o subidas de imágenes grandes. Además de todo lo anterior:

• Aumenta WP_MAX_MEMORY_LIMIT en wp-config.php: define(‘WP_MAX_MEMORY_LIMIT’, ‘512M’);
• Desactiva temporalmente los plugins de backup o seguridad mientras haces tareas largas desde la administración.
• Para importaciones, usa WP-CLI por SSH en lugar del importador web. No pasa por Nginx ni por los timeouts HTTP, y te ahorras el problema entero.

Conclusión

El error 504 Gateway Timeout en Nginx con PHP-FPM casi siempre se resuelve combinando tres ajustes: ampliar fastcgi_read_timeout en Nginx, sincronizar request_terminate_timeout y max_execution_time en PHP, y dimensionar bien el pool de procesos. Pero ojo: el timeout largo solo parchea el síntoma. Usa el slowlog de PHP-FPM y el log de consultas lentas para ir a por el script o la consulta que provoca la espera, que ahí está el problema de fondo. Y si tras todo esto el fallo persiste, en RedServicio (redservicio.net) puedes encontrar ayuda profesional para diagnosticar y optimizar tu servidor Nginx, PHP-FPM y WordPress al completo.