Un error 502 Bad Gateway en Nginx suele significar que Nginx no ha podido recibir una respuesta válida de un servidor de origen, como PHP-FPM, Node.js u otra aplicación de backend.
Las causas más habituales son servicios de aplicaciones detenidos, puertos o sockets de origen incorrectos y procesos de backend que fallan o cierran las conexiones de forma inesperada.
Empieza por revisar los registros de errores de Nginx. A menudo muestran exactamente por qué ha fallado la conexión.
Esta guía presenta siete pasos prácticos para diagnosticar problemas en servidores Linux que ejecutan Nginx.
¿Qué provoca un error 502 Bad Gateway en Nginx?
Nginx suele actuar como proxy inverso: reenvía las solicitudes a las aplicaciones de backend y devuelve sus respuestas a los visitantes.
Si el servicio de origen no responde correctamente, Nginx puede devolver el código de estado HTTP 502.
Entre las causas habituales se encuentran:
- Servicios de backend que se han detenido o han fallado.
- Direcciones IP, puertos o sockets Unix de origen incorrectos.
- Fallos de PHP-FPM o de los procesos de la aplicación.
- Problemas con los permisos de acceso al socket.
- Memoria o espacio en disco insuficientes.
- Conexiones con el servidor de origen no válidas o cerradas antes de tiempo.
Las siguientes comprobaciones presuponen que tienes acceso por SSH y permisos para administrar tu servidor Linux.
1. Revisa los registros de errores de Nginx
Los registros de errores de Nginx suelen ser la forma más rápida de identificar la causa de un error 502.
Conéctate a tu servidor por SSH y ejecuta:
sudo tail -n 50 /var/log/nginx/error.logEsto muestra las últimas 50 entradas del registro.
Para diagnosticar el problema en tiempo real, utiliza:
sudo tail -f /var/log/nginx/error.logVuelve a cargar la página web afectada y comprueba si aparecen mensajes nuevos.
| Mensaje del registro | Problema probable |
|---|---|
connect() failed (111: Connection refused) | El backend no acepta conexiones |
No such file or directory | No se encuentra el socket de origen configurado |
Permission denied | Nginx no puede acceder al socket o al recurso |
upstream prematurely closed connection | El backend ha cerrado la conexión de forma inesperada |
upstream sent invalid header | El backend ha devuelto cabeceras de respuesta mal formadas |
Es posible que tu configuración de alojamiento utilice otra ubicación para los registros.
No cambies la configuración de Nginx hasta que hayas identificado la causa probable.
2. Comprueba si el servicio de backend está en ejecución
Un error 502 suele producirse porque la aplicación situada detrás de Nginx se ha detenido.
Si systemd gestiona el servicio de la aplicación, ejecuta:
sudo systemctl status myappSustituye myapp por el nombre real de tu servicio.
En las aplicaciones basadas en PHP que utilizan PHP-FPM, el servicio podría tener un nombre como:
sudo systemctl status php8.3-fpmLa versión de PHP instalada y el nombre del servicio pueden variar.
Si el servicio ha fallado, examina sus registros:
sudo journalctl -u myapp -n 50Busca fallos, dependencias ausentes, errores de configuración o problemas relacionados con la memoria.
Reinicia el servicio solo después de identificar y solucionar el problema subyacente.
3. Comprueba el puerto o el socket de origen
Nginx debe reenviar las solicitudes a la dirección correcta del backend.
Por ejemplo, la configuración de un proxy inverso podría contener:
location / {
proxy_pass http://127.0.0.1:3000;
}Esto indica a Nginx que reenvíe las solicitudes a una aplicación HTTP que escucha en el puerto 3000.
Comprueba si hay algún servicio escuchando en ese puerto:
sudo ss -ltnp | grep ':3000'También puedes probar directamente un backend HTTP:
curl -i http://127.0.0.1:3000/Si el backend no está disponible, investiga la configuración de su servicio antes de cambiar Nginx.
Comprueba los sockets de PHP-FPM
PHP-FPM suele utilizar sockets Unix o puertos TCP.
Una configuración de Nginx podría contener:
fastcgi_pass unix:/run/php/php8.3-fpm.sock;Comprueba si existe el socket configurado:
ls -l /run/php/La ruta del socket debe coincidir con el ajuste listen del pool de PHP-FPM, y Nginx debe tener permiso para conectarse.
Importante: proxy_pass se utiliza para servidores de origen HTTP, mientras que fastcgi_pass se utiliza para servicios FastCGI como PHP-FPM. No son intercambiables.
4. Comprueba la memoria y el espacio en disco del servidor
Las aplicaciones de backend pueden fallar o dejar de responder cuando el servidor se queda sin recursos.
Comprueba la memoria:
free -hComprueba el espacio en disco:
df -hComprueba los procesos en ejecución:
topSi una aplicación se ha terminado por falta de memoria, puede que encuentres mensajes relacionados en el registro del sistema:
sudo journalctl -k --since "1 hour ago"Busca eventos de falta de memoria o mensajes de terminación de procesos.
Si se ha agotado el espacio en disco, averigua qué lo está ocupando antes de eliminar archivos.
5. Comprueba los permisos del socket y los registros de la aplicación
A veces el backend está en ejecución, pero Nginx no puede comunicarse con él.
Si utilizas sockets Unix, revisa su propietario y sus permisos:
ls -l /run/php/Si los registros indican un error de permisos, comprueba también los directorios de la ruta que conduce al socket.
Los permisos adecuados dependen del usuario de los procesos de trabajo de Nginx y de la configuración del servicio de backend.
Evita conceder permisos demasiado amplios, como chmod 777. En su lugar, ajusta la configuración del servicio o del pool correspondiente para que los procesos autorizados puedan acceder al socket.
Si los registros de errores indican que el servidor de origen ha cerrado la conexión antes de tiempo, examina los registros de la aplicación de backend en busca de fallos, excepciones o solicitudes fallidas.
6. Comprueba la configuración de Nginx
Una configuración incorrecta del proxy o ciertos cambios de configuración también pueden interrumpir la comunicación con el servidor de origen.
Antes de aplicar cambios, valida la configuración de Nginx:
sudo nginx -tSi la prueba se completa correctamente, recarga Nginx:
sudo systemctl reload nginxLa recarga aplica los cambios de configuración válidos sin reiniciar el servicio innecesariamente.
Si la prueba falla, corrige primero el error de configuración indicado.
No aumentes a ciegas los tiempos de espera del proxy ni los límites de los búferes. Estos ajustes no solucionarán un backend detenido, un socket incorrecto ni una conexión rechazada.
7. Confirma que se ha solucionado el error 502
Después de solucionar el problema subyacente, prueba la URL afectada:
curl -I https://example.comSustituye example.com por tu dominio real.
Una solicitud correcta suele devolver un estado HTTP apropiado, como 200 OK, aunque las redirecciones y otras respuestas válidas pueden generar códigos diferentes.
Abre también el sitio web en tu navegador y vuelve a revisar los registros de errores de Nginx.
Si el error reaparece cuando aumenta la carga, supervisa el servicio de backend y el uso de recursos mientras reproduces el problema.
Cómo prevenir los errores 502 en Nginx
No todos los fallos del backend se pueden evitar, pero una buena administración del servidor reduce las interrupciones evitables.
- Supervisa el estado de Nginx y del servicio de backend.
- Revisa los registros de la aplicación después de cada despliegue.
- Configura políticas adecuadas de recuperación de servicios.
- Supervisa el uso de memoria, almacenamiento y conexiones.
- Valida los cambios de configuración antes de aplicarlos.
- Prueba las aplicaciones directamente antes de dirigir el tráfico a través de Nginx.
Si una aplicación necesita más recursos, mide su uso real antes de decidir si aumentas la capacidad del servidor.
Preguntas frecuentes
Significa que Nginx, al actuar como puerta de enlace o proxy, ha recibido una respuesta no válida de un servidor de origen. La causa suele ser un servicio de backend detenido o un problema de conexión con el servidor de origen.
No necesariamente. Reiniciar o recargar Nginx no solucionará una aplicación que no está disponible, un puerto de backend incorrecto ni la ausencia de un socket de PHP-FPM.
Un error 502 indica que el servidor de origen ha enviado una respuesta no válida, mientras que un error 504 significa que la puerta de enlace no ha recibido una respuesta del servidor de origen dentro del tiempo de espera establecido.
Sí. Si se agota la memoria, los procesos de backend pueden fallar o terminarse, lo que impide que Nginx se comunique con ellos.
No. Otras puertas de enlace, proxies, CDN y balanceadores de carga también pueden devolver errores HTTP 502.
Conclusión
Para solucionar un error 502 Bad Gateway en Nginx, primero hay que averiguar por qué la aplicación de origen no responde correctamente.
Revisa primero los registros de errores de Nginx, confirma que el servicio de backend está en ejecución y comprueba el puerto o el socket configurado. Después, investiga los límites de recursos, los permisos y los fallos de la aplicación.
En la mayoría de los casos, identificar el fallo concreto del servidor de origen es más eficaz que reiniciar Nginx repetidamente o cambiar los tiempos de espera.
