502 Puerta de enlace no válida: qué significa realmente y cómo solucionarlo
Abres tu sitio web y en lugar de contenido ves una página en blanco que dice 502 Puerta de enlace no válida. Parece aterrador, pero en la mayoría de los casos la solución es sencilla. Vamos a desglosar lo que está sucediendo y cómo hacer que tu sitio vuelva a funcionar.
¿Qué significa realmente el error 502?
Cuando un visitante solicita una página, la solicitud generalmente pasa por dos capas: un servidor web frontend (generalmente Nginx) y un servidor de aplicaciones backend (PHP-FPM, Apache, Node.js o algo más). Nginx recibe la solicitud, la reenvía al backend y espera una respuesta.
Una 502 Puerta de enlace no válida significa que Nginx intentó obtener una respuesta del backend, pero recibió algo inválido o ninguna respuesta en absoluto. El backend o bien se cayó, rechazó la conexión o devolvió algo que Nginx no pudo interpretar.
Un concepto erróneo común: 502 no significa que tu servidor esté caído. El servidor en sí está bien; es la aplicación detrás de Nginx la que tiene problemas.
Causas más comunes
El servicio backend se ha detenido. Esta es la razón número uno. PHP-FPM se cayó, Apache se bloqueó o un proceso de Node.js murió silenciosamente. Nginx no tiene con quién hablar.
El servidor se está quedando sin RAM. Cuando la memoria se agota, Linux puede cerrar procesos que consumen muchos recursos automáticamente. Este mecanismo se llama el OOM killer y PHP-FPM o MySQL suelen ser sus primeras víctimas. Si esto ocurre regularmente, considera agregar un archivo de intercambio como red de seguridad.
El grupo de trabajo de PHP-FPM está agotado. Si tu sitio recibe más solicitudes simultáneas de las que PHP-FPM puede manejar, las nuevas solicitudes se ponen en cola y eventualmente expiran. Esto a menudo sucede cuando los bots de los motores de búsqueda rastrean tu sitio de forma demasiado agresiva; escribimos sobre cómo lidiar con eso en nuestra guía de bloqueo de bots.
Socket o puerto mal configurado. Nginx espera encontrar PHP-FPM en un socket Unix o puerto TCP específicos. Si la ruta en la configuración de Nginx no coincide con la configuración de PHP-FPM, verás errores 502 inmediatamente después de cualquier cambio.
Cómo diagnosticarlo
Para realizar los siguientes pasos, conéctate a tu servidor vía SSH. Puedes aprender cómo hacerlo en nuestro artículo sobre SSH.
Paso 1. Verifica si el backend está en ejecución
Verifica el estado de tu servicio backend:
sudo systemctl status php8.2-fpm
Reemplaza php8.2-fpm con tu versión de PHP real o el nombre de tu servicio backend. Si la salida dice inactive (dead) o failed, ese es tu problema. Reinícialo:
sudo systemctl restart php8.2-fpm
Luego, verifica el estado nuevamente para asegurarte de que se inició correctamente.
Paso 2. Verifica el registro de errores de Nginx
El registro de errores casi siempre te dice exactamente lo que salió mal:
sudo tail -30 /var/log/nginx/error.log
Si estás usando FASTPANEL®, también puedes ver los registros directamente en la interfaz web: abre la tarjeta del sitio, ve a la sección "Registros" y revisa la pestaña "Registro de errores del frontend".
Aquí están los mensajes de error más comunes y lo que significan:
connect() failed - Connection refused - el servicio backend no se está ejecutando. Reinícialo como se muestra en el Paso 1.
connect() failed - No such file or directory - Nginx está intentando acceder a un socket Unix que no existe. Verifica que la ruta del socket en tu configuración de Nginx coincida con lo que realmente crea PHP-FPM.
upstream sent too big header - el backend devolvió encabezados HTTP demasiado grandes para el buffer predeterminado. Añade estas líneas a la configuración de tu sitio Nginx dentro del bloque server:
fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
Después de editar, prueba la configuración y recarga Nginx:
sudo nginx -t && sudo systemctl reload nginx
Paso 3. Verifica los recursos del servidor
free -h
Si la columna available muestra menos de 100-200 MB de memoria libre, es probable que tu servidor se esté quedando sin RAM. Verifica qué la está consumiendo:
ps aux --sort=-%mem | head -10
Si la presión de memoria es la causa principal, la solución temporal más rápida es agregar un archivo de intercambio. Sin embargo, el intercambio en disco es mucho más lento que la RAM y no debe tratarse como una solución permanente. Si tu servidor se queda regularmente sin memoria, es hora de optimizar tus aplicaciones o actualizar a un plan con más RAM.
Conclusión
Una 502 Puerta de enlace no válida es casi siempre un problema del backend: un servicio caído, trabajadores agotados o falta de memoria. Verifica el estado del backend, lee el registro de errores de Nginx y observa el uso de tus recursos. En la gran mayoría de los casos, encontrarás la respuesta en minutos.
Si prefieres no lidiar con esto solo, en kodu.cloud ofrecemos soporte técnico gratuito 24/7 con cada VPS y servidor dedicado. Todos nuestros clientes también obtienen FASTPANEL® Extended sin costo adicional, lo que hace que el análisis de registros y la administración de servicios sean significativamente más fáciles a través de una interfaz web.