El error 502 bad gateway es de esos fallos que cualquier administrador de servidores con Nginx como fachada y PHP-FPM detrás ha visto más veces de las que le gustaría admitir. Vamos, casi un clásico. En esencia, significa que Nginx no ha recibido una respuesta válida del backend al intentar ejecutar un script: normalmente porque PHP-FPM ha dejado de responder, se ha bloqueado o directamente ha muerto. Para el visitante de un WordPress es alarmante, sí. Pero la buena noticia —y no es poca— es que en la mayoría de los casos la solución está al alcance de cualquier administrador con un poco de método. Aquí explico por qué ocurre, cómo diagnosticarlo y qué pasos concretos seguir para devolver la web a la vida en cuestión de minutos.
¿Qué significa el error 502 Bad Gateway y por qué ocurre en Nginx con PHP-FPM?
En una arquitectura típica de WordPress sobre Linux, Nginx actúa como puerta de enlace: recibe la petición HTTP del navegador y la pasa a PHP-FPM a través de un socket Unix o de una conexión TCP en el puerto 9000. Si Nginx no consigue comunicarse con PHP-FPM, o este le devuelve una respuesta inválida, o simplemente tarda demasiado, el resultado es el dichoso 502. Fíjate en un detalle: el problema casi nunca está en Nginx en sí, sino en lo que tiene detrás.
¿Y qué suele provocarlo? Pues esto:
- PHP-FPM detenido o bloqueado: el servicio se ha caído por un error fatal, un consumo excesivo de memoria o un fallo en una actualización de PHP.
- Ruta incorrecta del socket: Nginx intenta conectarse a /run/php/php-fpm.sock pero, tras una actualización de PHP, la versión del socket ha cambiado (digamos de php8.1-fpm.sock a php8.2-fpm.sock).
- Permisos insuficientes: el usuario de Nginx (normalmente www-data) no tiene permisos de lectura y escritura sobre el socket.
- Timeouts por carga alta: scripts que tardan más de lo permitido en fastcgi_read_timeout y hacen que Nginx cierre la conexión.
- Límites de recursos agotados: el parámetro pm.max_children de PHP-FPM se ha quedado corto para el tráfico actual.
Consejo práctico: si el error aparece justo después de actualizar la versión de PHP, la causa casi segura es una discrepancia en el nombre del socket entre Nginx y el nuevo pool de PHP-FPM. Lo he visto pasar muchísimas veces.
Primer paso: revisar los logs de Nginx y PHP-FPM para diagnosticar el problema
Antes de tocar nada de configuración, hay que identificar la causa exacta. A ciegas no se arregla nada. Los logs te dirán en segundos qué está fallando. Empieza por el log de errores de Nginx:
Consultar el log de Nginx
Ejecuta este comando y recarga la página afectada para generar una entrada nueva:
- Debian/Ubuntu: tail -f /var/log/nginx/error.log
- CentOS/RHEL/AlmaLinux: tail -f /var/log/nginx/error.log (o la ruta definida en nginx.conf)
Si ves mensajes como «connect() to unix:/run/php/php8.1-fpm.sock failed (2: No such file or directory)», el problema es la ruta del socket. Si aparece «connect() failed (111: Connection refused)», PHP-FPM no está escuchando o está caído. Y un mensaje «upstream timed out» apunta a scripts lentos o a un backend saturado.
Consultar el log de PHP-FPM
Segundo punto de diagnóstico: el log del pool de PHP-FPM, habitualmente en /var/log/php8.x-fpm.log. Busca líneas que indiquen que procesos hijos han sido terminados por agotamiento de memoria (señales SIGSEGV o SIGTERM) o avisos del tipo «server reached pm.max_children setting». Ese último aviso confirma que has agotado los procesos disponibles. No hay más margen.
¿Dónde están los logs si uso un panel como Plesk o un hosting gestionado? Suelen estar en /var/log/php-fpm/ o accesibles desde el propio panel. En RedServicio puedes encontrar guías específicas para cada panel.
Comprobar el estado del servicio PHP-FPM y reiniciarlo correctamente
Identificado el problema, toca verificar el estado del servicio. Un matiz importante: el nombre depende de la versión de PHP instalada.
- systemctl status php8.2-fpm (ajusta la versión a la tuya)
- systemctl status php-fpm en distribuciones basadas en RHEL
¿El servicio está inactivo o en estado de fallo? Reinícialo:
sudo systemctl restart php8.2-fpm && sudo systemctl status php8.2-fpm
Tras el reinicio, comprueba que Nginx también está en buen estado: sudo nginx -t para validar la configuración y sudo systemctl reload nginx para aplicarla sin cortar el servicio. En la mayoría de los casos de 502 causados por PHP-FPM caído, con esto la web vuelve a funcionar de inmediato. Pero atención. Si el error reaparece minutos después, el reinicio solo está tapando el problema real: agotamiento de memoria o límites del pool. Eso lo abordamos en la siguiente parte del artículo, con ajustes concretos de pm.max_children, permisos del socket y timeouts de Nginx.
Corregir la configuración del socket o puerto entre Nginx y PHP-FPM
La causa más frecuente del 502 bad gateway es casi trivial: Nginx intenta hablar con PHP-FPM por un socket o puerto que no coincide con el que PHP-FPM realmente está escuchando. ¿Y cómo lo compruebas? Primero mira qué socket tiene configurado el pool:
Abre el archivo del pool, normalmente /etc/php/8.1/fpm/pool.d/www.conf (ajusta la versión a la que tengas instalada), y localiza la directiva listen. Algo así:
- listen = /run/php/php8.1-fpm.sock (comunicación por socket Unix)
- listen = 127.0.0.1:9000 (comunicación por puerto TCP)
Luego ve al bloque correspondiente de Nginx, habitualmente en /etc/nginx/sites-available/tusitio.conf, y comprueba que fastcgi_pass apunte exactamente al mismo destino:
- fastcgi_pass unix:/run/php/php8.1-fpm.sock;
- fastcgi_pass 127.0.0.1:9000;
Un solo carácter de diferencia en la ruta del socket provoca el 502. Lo he visto más de una vez: una ruta copiada de otro servidor, una versión de PHP distinta en el nombre… y a depurar. Tras cualquier cambio, valida la sintaxis y reinicia ambos servicios:
- sudo nginx -t && sudo systemctl restart nginx
- sudo systemctl restart php8.1-fpm
Y no te olvides de los permisos del socket. Si Nginx corre como www-data, ese usuario debe poder leer y escribir en él. En el pool de PHP-FPM define:
- listen.owner = www-data
- listen.group = www-data
- listen.mode = 0660
Puedes ver los permisos reales con ls -l /run/php/php8.1-fpm.sock. ¿Propietario distinto a www-data? ¿Permisos restrictivos como 0664 en sistemas donde el grupo no coincide? Ahí tienes tu 502.
Ajustar límites de memoria, timeouts y procesos PHP-FPM para evitar el error 502 Bad Gateway
Puede que el socket esté bien configurado y aun así el 502 reaparezca cuando el sitio recibe tráfico. Entonces el problema suele ser otro: agotamiento de recursos. Vuelve al pool de PHP-FPM y revisa estas directivas en www.conf:
- pm.max_children: número máximo de procesos simultáneos. Para calcularlo, divide la RAM disponible para PHP entre el consumo medio por proceso; con 4 GB libres y procesos de 60 MB, un valor de 60 es razonable.
- pm.start_servers, pm.min_spare_servers y pm.max_spare_servers: ajústalos para mantener procesos de reserva y evitar picos de creación.
- pm.max_requests: un valor como 500 hace que los procesos se reciclen, lo que ayuda a mitigar fugas de memoria.
Si en /var/log/php8.1-fpm.log aparece un server reached pm.max_children setting, el diagnóstico está confirmado. Sube el valor poco a poco y vigila el consumo con htop o free -m.
Después revisa los timeouts en Nginx, dentro del bloque location ~ \.php$:
- fastcgi_read_timeout 300;
- fastcgi_connect_timeout 60;
- fastcgi_send_timeout 300;
Ojo aquí: valores demasiado bajos cortan scripts legítimos que tardan (importaciones, backups) y generan 502. Ajusta también request_terminate_timeout en PHP-FPM para que coincida con fastcgi_read_timeout. Y un detalle que muchos pasan por alto: memory_limit en php.ini tampoco conviene que sea excesivo. Si cada proceso puede comerse 512 MB, pocos caben en RAM.
Consejo práctico: tras cada ajuste, aplica carga de prueba con herramientas como ab o wrk y observa los logs de PHP-FPM en tiempo real con tail -f /var/log/php*-fpm.log. Así comprobarás que los cambios resuelven el problema en lugar de desplazarlo a otro sitio.
Conclusión: cómo prevenir futuros errores 502 en tu servidor
Un 502 bad gateway en Nginx con PHP-FPM casi siempre responde a lo mismo: socket o puerto mal configurado, permisos incorrectos en el socket, timeouts demasiado ajustados o un pool PHP-FPM que no da abasto con la carga real del sitio. Si sigues el orden de este artículo (verificar servicios, revisar logs, validar la comunicación Nginx-PHP-FPM y ajustar límites de recursos), resolverás la inmensa mayoría de casos en minutos.
Para que no vuelva a pasar, unas cuantas buenas prácticas:
- Monitoriza el consumo de memoria y los logs de PHP-FPM de forma periódica, sobre todo tras actualizar plugins o la versión de PHP.
- Configura monitorización con herramientas como Netdata, Monit o los alertadores de tu proveedor de hosting, para enterarte de las caídas antes que tus usuarios.
- Documenta cada cambio en la configuración. Cuando algo se rompa, agradecerés poder revertir rápido.
- Mantén Nginx y PHP-FPM actualizados y evita mezclar versiones de PHP con configuraciones heredadas de instalaciones anteriores.
¿Prefieres no lidiar con logs, sockets y pools de procesos? En RedServicio (redservicio.net) encontrarás ayuda profesional para diagnosticar y resolver cualquier error 502 bad gateway en tu servidor, con ajustes aplicados de forma segura y sin tiempos de parada innecesarios. Un servidor bien configurado no solo elimina el 502: mejora el rendimiento y la estabilidad de toda tu web.
