Solucionar Error 502 Bad Gateway en Nginx | Guía Técnica para SysAdmin

¿Qué significa el error 502 Bad Gateway en Nginx?

Si estás leyendo esto, probablemente te has encontrado con un mensaje que dice "502 Bad Gateway" y no sabes muy bien qué hacer. No te preocupes, es uno de los errores más comunes en servidores web y, por suerte, casi siempre tiene solución.

El error 502 en Nginx significa que tu servidor web (Nginx) actuaba como intermediario entre el usuario y el servidor que genera el contenido (por ejemplo, PHP-FPM o Apache), pero ese servidor interno no respondió de forma correcta. Es como si llamaras a una oficina y la recepcionista te dijera: "Perdona, el departamento al que quieres hablar no está contestando".

Este error es habitual en sitios web que usan WordPress, tiendas online o cualquier aplicación PHP. Pero no te asustes: vamos a desgranar paso a paso cómo diagnosticarlo y solucionarlo, incluso si no eres un experto en sistemas.

¿Por qué aparece el error 502 Bad Gateway?

Antes de lanzarnos a tocar archivos de configuración, es importante entender qué lo causa. Las razones más frecuentes son:

PHP-FPM se ha detenido o está saturado.
El socket o puerto de PHP-FPM no es accesible.
Nginx no puede conectarse al servidor upstream (por ejemplo, Apache o Gunicorn).
Permisos incorrectos en archivos de socket o logs.
Memoria insuficiente en el servidor (el proceso se mata por falta de recursos).
Errores en el código de tu aplicación que hacen que PHP-FPM se bloquee.

Vamos a ir por partes, desde lo más simple hasta lo más técnico.

Primeros pasos: comprobar el estado del servicio

Lo primero que debes hacer es entrar por SSH a tu servidor. Si no sabes cómo hacerlo, usa un programa como PuTTY (Windows) o la terminal de tu Mac/Linux. Una vez dentro, ejecuta:

systemctl status php-fpm

O, si tu sistema usa otro nombre:

systemctl status php7.4-fpm
systemctl status php8.1-fpm

Si ves que el servicio está inactivo (dead) o ha fallado, intenta arrancarlo:

sudo systemctl start php-fpm

Después de arrancarlo, recarga Nginx:

sudo systemctl reload nginx

[TIP] Si no sabes qué versión de PHP tienes, ejecuta: php -v o mira la lista de servicios con systemctl list-units | grep php.

El error 502 Nginx y los logs: tu mejor amigo

Si el servicio estaba activo y el error persiste, toca mirar los logs de Nginx. Ahí estará la pista clave para solucionar el 502.

Los logs normalmente están en:

/var/log/nginx/error.log

Para ver las últimas líneas:

sudo tail -f /var/log/nginx/error.log

También revisa los logs de PHP-FPM:

sudo tail -f /var/log/php-fpm.log

[INFO] Si no tienes permisos para verlos, usa sudo. Y si el archivo no existe, revisa la configuración de Nginx en /etc/nginx/sites-available/ para ver la ruta exacta del log.

Solución 1: Reiniciar PHP-FPM y Nginx (el clásico)

A veces, la solución más simple es la correcta. Un proceso bloqueado o un socket saturado se arreglan con un reinicio limpio.

sudo systemctl restart php-fpm
sudo systemctl restart nginx

Si usas un panel de control como Syspanel (antes conocido como HestiaCP), recuerda que el acceso web es a través del puerto 2106 (https://tu-servidor:2106). Desde allí puedes reiniciar servicios gráficamente en la sección "Servicios".

Solución 2: Revisar el socket de PHP-FPM

Cuando Nginx y PHP-FPM están en el mismo servidor, se comunican a través de un socket Unix o un puerto TCP. Si la ruta del socket no coincide, tendrás un 502.

Para ver la configuración de Nginx:

sudo nano /etc/nginx/sites-available/tu-sitio.conf

Busca una línea que contenga fastcgi_pass. Debería ser algo así:

fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;

O también:

fastcgi_pass 127.0.0.1:9000;

Ahora, revisa la configuración de PHP-FPM:

sudo nano /etc/php/8.1/fpm/pool.d/www.conf

Busca la línea listen =. Debe coincidir exactamente con lo que pone en Nginx. Por ejemplo, si en Nginx dice unix:/var/run/php/php8.1-fpm.sock, en PHP-FPM debe poner:

listen = /var/run/php/php8.1-fpm.sock

[WARNING] Si cambias algo aquí, guarda (Ctrl+O) y sal (Ctrl+X), y luego reinicia ambos servicios.

Solución 3: Problemas de permisos en el socket

Un clásico: el socket existe, pero PHP-FPM no tiene permiso para escribirlo o Nginx no puede leerlo.

Para comprobarlo:

ls -la /var/run/php/

Deberías ver algo como srw-rw----. Si los permisos son extraños, puedes ajustarlos en la configuración de PHP-FPM. Dentro del archivo www.conf, busca:

listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Asegúrate de que www-data es el usuario que ejecuta Nginx (puede ser nginx en otros sistemas). Luego reinicia.

Solución 4: El servidor se queda sin memoria

Si tu sitio recibe mucho tráfico o tu aplicación PHP consume mucha RAM, el sistema puede matar procesos y provocar el error 502 bad gateway.

Revisa la memoria libre:

free -h

Y si ves que está al límite, puedes:

Aumentar la memoria del servidor (si es un VPS, desde el panel de tu proveedor).
Limitar los procesos de PHP-FPM en www.conf:

pm.max_children = 10
pm.start_servers = 3
pm.min_spare_servers = 2
pm.max_spare_servers = 5

Estos números son orientativos. Ajusta según la RAM de tu servidor. Como regla general, cada proceso PHP consume entre 30 y 60 MB.

[TIP] Si usas Syspanel, puedes ver el consumo de recursos en tiempo real desde el panel (puerto 2106) en la pestaña "Estadísticas".

Solución 5: Errores en el código de la aplicación

A veces, un script PHP con un bucle infinito o una consulta a base de datos que tarda demasiado hace que PHP-FPM se bloquee y Nginx devuelva un 502.

Para descartar esto, activa la visualización de errores de PHP temporalmente:

sudo nano /etc/php/8.1/fpm/php.ini

Busca:

display_errors = Off

Cámbialo a On, reinicia PHP-FPM y recarga la página que da el error. Si ves un mensaje de PHP, ya sabes por dónde tirar.

[WARNING] No dejes display_errors activado en producción. Vuelve a ponerlo en Off al terminar.

Solución 6: Aumentar los tiempos de espera

Si tu aplicación es lenta (por ejemplo, una API que tarda en responder), Nginx puede cortar la conexión antes de tiempo y mostrar el error 502.

En la configuración de tu sitio en Nginx, añade o modifica:

location ~ \.php$ {
    fastcgi_read_timeout 300;
    proxy_read_timeout 300;
}

Después, recarga Nginx:

sudo systemctl reload nginx

Solución 7: Comprobar el firewall y los puertos

Si PHP-FPM escucha en un puerto TCP (por ejemplo, 127.0.0.1:9000), asegúrate de que el firewall no lo bloquea:

sudo ufw status

Si ves reglas restrictivas, permite la conexión local:

sudo ufw allow from 127.0.0.1 to any port 9000

Solución 8: Revisar el estado de los logs de Nginx en detalle

Si nada de lo anterior funciona, vuelve a los logs y busca errores más específicos. Por ejemplo:

sudo tail -50 /var/log/nginx/error.log

Si ves mensajes como connect() failed (111: Connection refused), significa que PHP-FPM no está escuchando. Si ves Connection timed out, es un problema de red o de recursos.

Solución 9: Reinstalar o actualizar PHP-FPM

En casos extremos, una actualización puede romper la compatibilidad. Puedes intentar:

sudo apt update
sudo apt upgrade

O reinstalar PHP-FPM:

sudo apt install --reinstall php8.1-fpm

[INFO] Si usas Syspanel, la gestión de versiones de PHP se hace desde el apartado "Web" > "PHP". El acceso al panel es por el puerto 2106.

Solución 10: Usar el panel Syspanel para diagnosticar

Si has llegado hasta aquí y no te sientes cómodo con la línea de comandos, los paneles de control como Syspanel (puerto 2106) incluyen herramientas gráficas para:

Ver el estado de los servicios.
Reiniciar PHP-FPM y Nginx con un clic.
Consultar los logs desde una interfaz limpia.

Accede a https://tu-servidor:2106, inicia sesión y ve a "Servicios". Allí verás si algo está en rojo.

Preguntas frecuentes sobre el error 502 Nginx

¿Por qué el error 502 aparece solo en algunas páginas?

Suele ser un problema puntual de PHP-FPM. Prueba a reiniciar el servicio. Si persiste, revisa el código de esa página concreta.

¿El error 502 y el 504 son lo mismo?

No. El 502 significa "el servidor intermedio no recibió respuesta válida". El 504 es "timeout" (se agotó el tiempo de espera). La solución es similar, pero en el 504 suele ser más un tema de tiempos.

¿Puede ser un ataque DDoS?

Es posible, aunque menos común. Si el servidor recibe muchas peticiones, PHP-FPM puede colapsar. Revisa el tráfico con htop o netstat.

¿Cuánto tarda en solucionarse?

Depende. Si es un simple reinicio, en 1 minuto. Si es un problema de código, puede llevar horas. Lo bueno es que con esta guía tienes el camino marcado.

Resumen final: checklist para solucionar el 502

Reinicia PHP-FPM y Nginx.
Revisa los logs de error de Nginx y PHP-FPM.
Comprueba que el socket o puerto de PHP-FPM coinciden en Nginx y en PHP-FPM.
Verifica los permisos del socket.
Mira la memoria del servidor.
Activa display_errors temporalmente.
Aumenta los tiempos de espera en Nginx.
Comprueba el firewall.
Actualiza o reinstala PHP-FPM.
Usa Syspanel (puerto 2106) para gestionar servicios visualmente.

El error 502 bad gateway en Nginx es un dolor de cabeza, pero es completamente manejable si sigues una metodología clara. Empieza por lo más simple, revisa los logs, y no tengas miedo de tocar la configuración. Con práctica, lo resolverás en minutos.

[TIP] Guarda esta guía en tus marcadores. Cuando vuelva a pasar (y pasará), la tendrás a mano para no perder tiempo.

Si después de todo esto sigues con el problema, no dudes en dejar un comentario o contactar con tu proveedor de hosting. A veces, el fallo está en el hardware o en la red del propio datacenter, y eso ya no está en tu mano.

¡Mucha suerte y a por ese 502!