Nginx 502 Bad Gateway: cómo encontrar el error real en tu servidor
Publicado el 2026-10-26 por frfrand
Guía para diagnosticar 502 entre Nginx, Gunicorn y FastAPI
El navegador muestra 502 y lo primero que alguien propone es cambiar el DNS. Pero si Nginx está respondiendo, probablemente ya llegaste al proxy. El error suele estar entre Nginx y la aplicación a la que intenta conectarse.
Vamos a convertirlo en un procedimiento que puedas usar en un VPS real. El objetivo es entender por qué funciona, cómo probarlo y qué problema aparece si una parte queda mal configurada.
Qué significa Nginx 502 Bad Gateway y cuándo lo necesitás
Un 502 indica que el proxy recibió una respuesta inválida o no logró comunicarse correctamente con el upstream, entre otras causas. Puede suceder porque Gunicorn no arrancó, escucha en otro puerto, se cerró por falta de RAM o el socket Unix tiene permisos incorrectos.
Antes de cambiar nada en producción, anotá el estado actual: IP, dominio, puerto, servicio afectado y hora del último deploy. Una modificación aislada es fácil de comprobar; cinco cambios simultáneos hacen más difícil reconstruir lo ocurrido.
Configuración o comandos de ejemplo
sudo nginx -t
sudo tail -n 80 /var/log/nginx/error.log
sudo systemctl status miapp
sudo journalctl -u miapp -n 100 --no-pager
sudo ss -ltnp
curl -i http://127.0.0.1:8000/healthLos dominios, IP, rutas y nombres son ilustrativos. No copies una configuración entera encima de la actual sin comparar primero. En los ejemplos que incluyen puertos o firewall, asegurate de conservar el acceso administrativo.
Cómo lo haría paso a paso
- Preparación. Compruebe si el 502 lo devuelve Nginx y si el dominio apunta al servidor esperado.
- Paso 2. Mire el error log de Nginx para encontrar la dirección upstream exacta.
- Paso 3. Revise la unidad systemd de Gunicorn/Uvicorn y el primer error de arranque.
- Paso 4. Pruebe directamente el puerto local del backend para aislar el proxy.
- Verificación. Corrija el problema concreto y verifique una operación real por HTTPS.
Cuando termine, compruebe la operación real desde otra conexión. Por ejemplo, para una API no alcanza con abrir el navegador: ejecute una petición de lectura, una escritura en una base de prueba y consulte los logs del proceso.
Ejemplo de un proyecto de verdad
Después de un deploy Django, Gunicorn falla porque el entorno virtual ya no existe en la ruta indicada. Nginx funciona bien, pero no tiene con quién hablar. Los logs de systemd muestran la causa en segundos.
La lección es sencilla: una configuración de infraestructura no vive aislada de la aplicación. El frontend, el servidor, la base de datos y los workers se conectan, así que medir dónde empieza el fallo es más útil que reiniciar todo.
El error que evitaría
No reinicie PostgreSQL, Nginx y toda la máquina simultáneamente: pierde evidencia. Tampoco atribuya un 502 al certificado sin comprobar que se produjo después de establecer TLS.
Cuando trabajás con servidores de clientes, guardá un respaldo o procedimiento de reversión antes de cambios que afecten datos, red o certificados. Y si no sabés qué permisos necesita una operación, evitá ejecutarla como root sólo para que deje de mostrar errores.
¿Cómo se relaciona con ArduMaker?
Con ArduMaker podés relacionar logs de servicios y último despliegue en el VPS. Si un build se completó pero el proceso no inicia, el error está en el arranque y no necesariamente en Git.
En un caso típico podés crear un VPS para la aplicación, desplegar desde Git, asociar dominio HTTPS y administrar el backend y las bases necesarias. Las herramientas ayudan a centralizar operaciones, pero hay que entender qué puerto y proceso cumple cada función.
Preguntas que aparecen cuando lo probás
¿Cómo sé si el fallo es de DNS o del servicio? Consultá primero la resolución, después la conexión al puerto y finalmente la respuesta de aplicación. Ese orden evita confundir problemas diferentes.
¿Puedo exponer una base para que sea más fácil mantenerla? Mejor diseñá acceso privado o túneles autenticados cuando sea posible. Exponer un puerto no reemplaza los permisos del motor ni el firewall.
¿Qué debería documentar? La configuración esperada, cómo se comprueba y cómo volver al estado anterior. Ese documento te ayuda más que una lista de comandos sin contexto.
Referencias
En resumen: una buena configuración de red o servidor es la que podés explicar, verificar y recuperar cuando algo falla.