Uno de los errores más comunes y confusos que puedes encontrar al administrar un servidor web es el 502 Bad Gateway. Si usas Nginx, esta página de error a menudo aparece de forma abrupta, bloqueando completamente el acceso a tu aplicación. Esta guía te explicará exactamente qué significa este error, sus causas principales y cómo solucionarlo de manera confiable.

El Error

Cuando intentas visitar tu sitio web, el navegador muestra una pantalla blanca con texto en negro que dice:

502 Bad Gateway
nginx/1.24.0

Tras bambalinas, si inspeccionas el log de errores de Nginx ubicado en /var/log/nginx/error.log, normalmente encontrarás un mensaje como:

2026/02/27 10:15:30 [error] 12345#0: *6789 connect() failed (111: Connection refused) while connecting to upstream, client: 192.168.1.10, server: example.com, request: "GET / HTTP/1.1", upstream: "fastcgi://127.0.0.1:9000"

Causa del Problema

A diferencia de un error 404 (Página no encontrada), un error 502 indica un problema de comunicación de servidor a servidor. Nginx está funcionando como un proxy inverso. Tomó la solicitud de tu navegador, se la pasó a un servidor de aplicaciones backend (denominado “upstream”) y ese servidor no respondió o devolvió una respuesta no válida.

Los culpables más frecuentes incluyen:

  1. El servicio Backend está inactivo: La aplicación upstream (por ejemplo, PHP-FPM, un proceso Node.js, Python Gunicorn o un contenedor Docker) se ha bloqueado o no se está ejecutando.
  2. Configuración incorrecta de socket o puerto: Nginx está intentando enviar tráfico a un puerto específico (como 127.0.0.1:9000) o a un socket Unix (como /var/run/php/php8.1-fpm.sock), pero la aplicación backend está escuchando en otro lugar.
  3. Timeouts (Agotamiento de tiempo) de la aplicación: La aplicación backend tardó demasiado en procesar la solicitud (por ejemplo, una consulta masiva a la base de datos), superando el límite de tiempo de espera predefinido de Nginx.
  4. Bloqueos de Firewall: Un firewall local como ufw o iptables está bloqueando el puerto que usa Nginx para comunicarse con el backend.
  5. Problemas de permisos: Nginx no tiene los permisos necesarios del sistema de archivos para leer y escribir en el archivo socket Unix del backend.

Solución Paso a Paso

Paso 1: Revisar el Log de Errores de Nginx

La mejor manera absoluta de resolver un error 502 es preguntarle a Nginx exactamente qué salió mal. Ejecuta este comando:

sudo tail -n 20 /var/log/nginx/error.log

Probablemente verás una de estas dos cosas:

  • “Connection refused”: El backend está inactivo o escuchando en el puerto equivocado.
  • “Upstream timed out”: El backend se está ejecutando pero tardó demasiado en responder.

Paso 2: Verificar el Servicio Backend Upstream

Si el error es “Connection refused”, tu aplicación de destino probablemente esté inactiva. Determina a qué backend intenta acceder Nginx (Node.js, PHP, Python) y comprueba su estado.

Para PHP-FPM:

sudo systemctl status php8.1-fpm

(Reemplaza 8.1 con tu versión instalada).

Si dice inactive (dead) o failed, inícialo:

sudo systemctl restart php8.1-fpm

Paso 3: Comprobar las Configuraciones del Bloque de Servidor

Si el servicio backend se está ejecutando activamente pero aún obtienes un 502, Nginx está apuntando al lugar equivocado.

Abre el archivo de configuración de Nginx para el sitio (generalmente en /etc/nginx/sites-available/your_domain o /etc/nginx/conf.d/default.conf) y localiza el bloque location que maneja el backend:

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    ...
}

O para configuraciones de proxy:

location / {
    proxy_pass http://127.0.0.1:3000;
}

Verificación Crucial: Garantiza que la ruta o el puerto especificado coincida realmente con tu backend. Para PHP, verifica que el socket exista:

ls -la /var/run/php/php8.1-fpm.sock

Si tu grupo (pool) PHP está configurado para escuchar en TCP 127.0.0.1:9000, cambia fastcgi_pass en Nginx para que coincida exactamente.

Paso 4: Arreglar los Permisos de Archivos Socket

Si utilizas sockets Unix, Nginx necesita permiso para leerlos. Por defecto, Nginx se ejecuta como www-data (en Debian/Ubuntu) o nginx (en CentOS/RHEL).

Si ls -la muestra que el socket es propiedad de root:root con permisos restringidos, a Nginx se le denegará el acceso, lanzando un 502. Asegúrate de que la configuración de tu grupo (pool) backend (p. ej., /etc/php/8.1/fpm/pool.d/www.conf) tenga la configuración correcta de usuario y grupo:

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

Paso 5: Incrementar los Tiempos de Espera (Timeouts) del Servidor

Si tu registro de errores mostró “Upstream timed out” durante un proceso de larga duración (como una carga de archivos grande o una exportación compleja de base de datos), necesitas darle más paciencia a Nginx.

Añade estas directivas dentro de tu bloque location:

Para Proxies HTTP (Node.js, Python, Java):

proxy_read_timeout 300s;
proxy_connect_timeout 75s;

Para PHP-FPM (FastCGI):

fastcgi_read_timeout 300s;

Recarga Nginx para aplicar los cambios:

sudo nginx -s reload

Prevención

Para evitar que los errores 502 cieguen a tus usuarios:

  • Configura el Reinicio Automático de Servicios: Asegúrate de que tus servicios backend (como las aplicaciones Node.js bajo PM2 o los servicios de systemd) estén configurados para reiniciarse automáticamente si se bloquean.
  • Implementa Chequeos de Salud (Health Checks): Utiliza herramientas como Monit o servicios externos como Pingdom para monitorear tu puerto backend sin procesar directamente, no solo Nginx.
  • Optimiza Consultas Lentas: Si los agotamientos de tiempo (timeouts) causan tus 502, incrementar el límite es una curita temporal. Optimiza las consultas a tu base de datos y la lógica de la aplicación para que nada tarde 5 minutos en cargar en el navegador.

Resumen

  • Un 502 Bad Gateway en Nginx significa que el proxy inverso no pudo recuperar una respuesta válida de la aplicación backend (upstream).
  • Casi nunca es un problema con Nginx en sí, sino más bien que el proceso backend se ha bloqueado, está mal configurado o se está agotando el tiempo de espera.
  • La forma más rápida de diagnosticarlo es revisar /var/log/nginx/error.log.
  • Soluciónalo verificando que el backend se esté ejecutando, asegurándote de que la ruta del puerto o socket en proxy_pass coincida perfectamente con la realidad, y ajustando los permisos o límites de tiempo de espera si es necesario.

Artículos Relacionados