Cómo Solucionar el Error Nginx 502 Bad Gateway en Linux Paso a Paso

Introducción

El error 502 Bad Gateway es uno de los problemas más comunes a los que se enfrentan los administradores de sistemas al gestionar servidores web basados en Linux. Este código de estado HTTP indica que el servidor web (en este caso, Nginx) actuaba como un proxy inverso y no pudo obtener una respuesta válida del servidor backend (como PHP-FPM, Node.js o uWSGI).

Causas Principales del Error 502 en Nginx

Antes de aplicar cualquier solución, es importante entender qué origina este fallo en entornos Linux:

• El servicio backend (ej. PHP-FPM) está detenido o se ha caído.
• Configuración incorrecta del socket o puerto TCP en el archivo de bloques de servidor de Nginx.
• Tiempos de espera agotados (Timeouts) debido a scripts lentos o consultas pesadas a la base de datos.
• Falta de recursos en el servidor (memoria RAM o CPU al 100%).

Método 1: Verificar y Reiniciar el Servicio Backend (PHP-FPM)

En la mayoría de los casos en distribuciones como Ubuntu o Debian, Nginx se comunica con PHP-FPM. Si este servicio falla, obtendrás un error 502.

1. Accede a tu servidor Linux mediante SSH.
2. Comprueba el estado actual del servicio PHP-FPM ejecutando el siguiente comando en la terminal:
   sudo systemctl status php8.1-fpm (reemplaza 8.1 por tu versión de PHP).
3. Si el servicio está detenido o presenta errores, reinícialo con el comando:
   sudo systemctl restart php8.1-fpm
4. Verifica que Nginx siga funcionando correctamente:
   sudo systemctl restart nginx

Método 2: Revisar la Configuración de los Sockets en Nginx

Una ruta incorrecta en el archivo de configuración del proxy inverso impedirá que Nginx se comunique con el backend.

1. Abre el archivo de configuración de tu sitio en Nginx, por ejemplo:
   sudo nano /etc/nginx/sites-available/tusitio.com
2. Busca la directiva fastcgi_pass o proxy_pass y asegúrate de que la ruta del socket Unix o la dirección IP y puerto sean correctos. Un ejemplo típico con socket es:
   fastcgi_pass unix:/run/php/php8.1-fpm.sock;
3. Si prefieres usar TCP, asegúrate de que coincida con el puerto configurado en PHP-FPM:
   fastcgi_pass 127.0.0.1:9000;
4. Guarda los cambios, sal del editor y comprueba la sintaxis de Nginx:
   sudo nginx -t
5. Si todo es correcto, recarga Nginx:
   sudo systemctl reload nginx

Método 3: Ajustar los Valores de Timeout en Nginx

Si tus aplicaciones ejecutan procesos largos que tardan en responder, Nginx cortará la conexión antes de tiempo devolviendo un 502.

1. Abre el archivo de configuración principal de Nginx:
   sudo nano /etc/nginx/nginx.conf
2. Agrega o modifica las siguientes directivas dentro del bloque http { ... } para ampliar el tiempo de espera:
   proxy_connect_timeout 600;
proxy_send_timeout 600;
proxy_read_timeout 600;
send_timeout 600;
3. Guarda el archivo y aplica los cambios reiniciando Nginx:
   sudo systemctl restart nginx