Corrección de errores 502 Bad Gateway en Nginx: Guía paso a paso
Rastree errores 502 de Nginx verificando configuración, estado del upstream, registros, sockets, redes Docker y síntomas de tiempo de espera.
Corrección de errores 502 Bad Gateway en Nginx: Guía paso a paso
Corregir errores 502 Bad Gateway de Nginx comienza por entender que Nginx suele ser el mensajero, no la fuente original de la falla. Un 502 significa que Nginx intentó comunicarse con un servicio upstream y no obtuvo una respuesta válida.
Ese servicio upstream podría ser una aplicación Node.js, PHP-FPM, Gunicorn, Puma, un contenedor u otro servidor HTTP. Su trabajo es encontrar dónde falla la transferencia.
Qué significa un error 502 Bad Gateway en Nginx
Nginx comúnmente se sitúa frente a un servidor de aplicaciones. Acepta tráfico público, maneja TLS, sirve archivos estáticos y reenvía solicitudes dinámicas al upstream.
Un 502 aparece cuando esa conexión upstream falla o devuelve algo que Nginx no puede usar. Las causas comunes incluyen:
- El proceso de la aplicación está detenido.
- Nginx apunta al puerto o socket incorrecto.
- Un socket Unix tiene permisos incorrectos.
- El servicio upstream falla durante la solicitud.
- Un firewall o red de contenedores bloquea la conexión.
- El upstream envía una respuesta HTTP no válida.
Comience con la ruta de solicitud exacta que falla. Si solo /api devuelve 502 pero las páginas estáticas cargan, su servicio de archivos estáticos está bien y el proxy o backend de la aplicación es probablemente el problema. Si cada página falla, el problema puede ser un problema más amplio de Nginx, DNS o disponibilidad del upstream.
Paso 1: Verificar el estado y la configuración de Nginx
Primero confirme que Nginx se está ejecutando:
systemctl status nginx
Luego pruebe la configuración:
nginx -t
Si la prueba de configuración falla, arréglela antes de perseguir la aplicación. Nginx puede seguir ejecutándose con una configuración anterior, o puede fallar al recargar.
Después de una prueba de configuración exitosa, recargue Nginx:
systemctl reload nginx
No reinicie a ciegas en un servidor ocupado a menos que comprenda el impacto. La recarga suele ser suficiente después de un cambio de configuración y es menos disruptiva.
A continuación, inspeccione el bloque de servidor activo. Busque proxy_pass, fastcgi_pass o uwsgi_pass. Un proxy inverso típico podría incluir:
location / {
proxy_pass http://127.0.0.1:3000;
}
Eso significa que Nginx espera una aplicación en el puerto local 3000. Si la aplicación realmente escucha en 3001, o solo dentro de una red Docker, Nginx fallará.
Para comprobaciones más centradas en comandos, consulte Comandos de prueba de configuración de Nginx.
Paso 2: Verificar el servicio upstream
Ahora pruebe el upstream directamente desde el host de Nginx. Si Nginx redirige a 127.0.0.1:3000, ejecute:
curl -i http://127.0.0.1:3000/
Si eso falla, el problema no es el navegador o el DNS público. Nginx no puede alcanzar el backend porque el backend está caído, escuchando en otro lugar o rechazando la solicitud.
Verifique el proceso de la aplicación:
ss -ltnp
Busque el puerto esperado. Si el servicio usa un socket Unix, verifique la ruta del socket:
ls -l /run/app/app.sock
El usuario trabajador de Nginx debe poder acceder a ese socket. En muchos sistemas Linux, Nginx se ejecuta como www-data, nginx o un usuario específico del servicio. Si el socket es propiedad de un usuario diferente y no es legible o escribible por el grupo según sea necesario, Nginx puede registrar un error de permiso y devolver 502.
Para una configuración de PHP-FPM, confirme que el pool se está ejecutando:
systemctl status php-fpm
El nombre del servicio puede incluir una versión, como php8.2-fpm, dependiendo de la distribución.
Paso 3: Leer el registro de errores de Nginx
El registro de errores de Nginx generalmente le indica qué modo de falla está enfrentando. Los mensajes de registro comunes incluyen:
connect() failed (111: Connection refused) while connecting to upstream
Esto significa que Nginx alcanzó el host pero nada aceptó la conexión en ese puerto.
upstream timed out while reading response header from upstream
Esto significa que Nginx se conectó, pero el backend no respondió a tiempo.
permission denied while connecting to upstream
Esto a menudo apunta a permisos de socket Unix o controles de seguridad como SELinux.
Verifique errores recientes con:
tail -n 100 /var/log/nginx/error.log
En sistemas basados en systemd, también puede verificar:
journalctl -u nginx -n 100
Haga coincidir la marca de tiempo en el registro con la hora de su solicitud del navegador. Esto evita que persiga errores antiguos que ya no son relevantes.
Para un flujo de trabajo de registro más profundo, consulte análisis de registros de errores de Nginx.
Paso 4: Corregir las causas raíz más comunes
Una vez que conozca el modo de falla, aplique la corrección más pequeña que coincida.
Si la aplicación no se está ejecutando, inicie o reinicie el servicio de la aplicación:
systemctl restart your-app
Luego pruebe el upstream con curl antes de probar a través de Nginx.
Si Nginx apunta al puerto incorrecto, actualice el destino proxy_pass y recargue Nginx. Asegúrese también de que su aplicación y Nginx estén de acuerdo sobre IPv4 versus IPv6. Una aplicación que escucha en 127.0.0.1 no es lo mismo que una que escucha solo en ::1.
Si Docker está involucrado, verifique si Nginx se ejecuta en el host o dentro de un contenedor. 127.0.0.1 dentro de un contenedor apunta a ese contenedor, no al host. Es posible que necesite un nombre de servicio Docker, red puente o puerto publicado.
Si el upstream agota el tiempo de espera, verifique los registros de la aplicación. El backend puede estar atascado en consultas de base de datos, llamadas API externas o trabajo de inicio. Aumentar los tiempos de espera de Nginx puede ocultar síntomas, pero no solucionará una aplicación rota o sobrecargada.
Cuándo llamar a un profesional
Traiga a un ingeniero senior o proveedor de alojamiento cuando los errores 502 afecten la producción y la causa no sea obvia después de verificar registros, estado del upstream e implementaciones recientes. También busque ayuda si el problema afecta balanceadores de carga, orquestación de contenedores, políticas SELinux o ajuste de tiempo de espera de alto tráfico.
Para sistemas de producción, evite reinicios aleatorios repetidos. Pueden borrar evidencia y hacer que la interrupción sea más difícil de entender.
Un error 502 Bad Gateway se puede solucionar cuando rastrea la ruta de la solicitud en orden. Confirme que Nginx sea válido, pruebe el upstream directamente, lea la línea exacta del registro de errores y aplique la corrección que coincida con la falla. Ese enfoque es más rápido y seguro que cambiar tiempos de espera o reiniciar servicios a ciegas.