Error 502 Bad Gateway: encontrar la causa y solucionarlo

Qué significa el error

Un 502 es la respuesta de un servidor que funciona. El servidor web que está delante (nginx, Apache, un balanceador de carga o un CDN como Cloudflare) recibió la petición, la pasó a la aplicación que tiene detrás (PHP-FPM, un proceso de Node.js o de Python) y no recibió nada utilizable de vuelta: conexión rechazada, cortada o respuesta ilegible. « Gateway » es el servidor que está delante; « bad » es lo que volvió de atrás. Un 502 dice, por tanto, dos cosas: delante, todo funciona; detrás, algo está detenido o roto.

Causas frecuentes

1. El proceso de la aplicación no se está ejecutando. PHP-FPM falló o fue detenido, el proceso de Node.js murió, el contenedor terminó.
2. La aplicación está saturada. Todos los workers de PHP-FPM están ocupados, la cola está llena, las nuevas conexiones se rechazan. Suele pasar tras un pico de visitas o por una consulta SQL lenta.
3. Socket o puerto incorrecto. Tras un cambio de versión de PHP, nginx sigue apuntando a php8.2-fpm.sock mientras el nuevo pool escucha en php8.4-fpm.sock.
4. Tiempos de espera demasiado cortos. El backend responde, pero demasiado tarde para el servidor web. Algunas configuraciones lo señalan como 502; otras, como 504 Gateway Timeout.
5. El backend envía cabeceras demasiado grandes. Típico de los frameworks que cargan las cookies.
6. El CDN no llega a tu servidor. Una página 502 con el logo de Cloudflare significa que Cloudflare no recibió nada de tu servidor: firewall, IP incorrecta tras una migración o servidor apagado.

Si eres visitante

Un 502 en un sitio que no es tuyo no se arregla de tu lado. Recarga pasado un minuto; si persiste, solo puede actuar quien lo gestiona.

Si el sitio es tuyo: comprobar primero

¿Está caído para todo el mundo? Abre el Website down checker: código HTTP visto desde fuera, y quién respondió, el CDN o el servidor.

¿Hosting compartido o creador de sitios web? Ahí un 502 es casi siempre un problema del proveedor de hosting (un pool de PHP saturado en un servidor compartido). Pasa al mensaje listo para enviar, más abajo.

Tu propio servidor: conéctate por SSH y lee lo que dice el servidor web.

# nginx: los últimos errores, los más recientes abajo
sudo tail -n 50 /var/log/nginx/error.log

# Apache (Debian/Ubuntu)
sudo tail -n 50 /var/log/apache2/error.log

Líneas típicas y su significado:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM no se está ejecutando, o la ruta del socket es incorrecta.
• connect() failed (111: Connection refused) while connecting to upstream: nada escucha en el puerto del backend.
• upstream prematurely closed connection: el backend falló mientras respondía, a menudo por un error fatal de PHP o por falta de memoria.
• upstream sent too big header: sube fastcgi_buffer_size en nginx.
• (11: Resource temporarily unavailable): todos los workers de PHP-FPM están ocupados.

Soluciones en tu propio servidor

1. Iniciar el servicio detenido

systemctl status php8.3-fpm
sudo systemctl start php8.3-fpm

# aplicaciones Node.js o Python bajo systemd
sudo systemctl restart mi-app

Si no arranca, el motivo está en journalctl -u php8.3-fpm -n 50. Lo más frecuente: un disco lleno (df -h) y, después, un error de sintaxis en un pool (sudo php-fpm8.3 -t).

2. Corregir el socket o el puerto

Compara la dirección a la que se conecta nginx con la dirección en la que escucha PHP-FPM:

grep -r fastcgi_pass /etc/nginx/sites-enabled/
grep -r '^listen' /etc/php/*/fpm/pool.d/

Las dos tienen que coincidir. Tras cualquier cambio, prueba antes de recargar:

sudo nginx -t && sudo systemctl reload nginx

Con Apache y mod_proxy_fcgi rige la misma regla para la línea SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; la prueba es sudo apachectl configtest.

3. Darle aire a PHP-FPM

Si el log indica server reached pm.max_children, sube el límite en el archivo del pool (/etc/php/8.3/fpm/pool.d/www.conf):

pm = dynamic
pm.max_children = 20
pm.start_servers = 4
pm.min_spare_servers = 2
pm.max_spare_servers = 6

Cada worker consume memoria; comprueba free -m antes de subirlo y busca la consulta lenta o el plugin que bloquea los workers.

4. El caso de WordPress

Un 502 justo después de actualizar un plugin o un tema: PHP tropieza en cada petición con un error fatal o con falta de memoria. Cambia el nombre de la carpeta del plugin por SFTP o SSH (wp-content/plugins/nombre-plugin a nombre-plugin.off) o ejecuta wp plugin deactivate nombre-plugin, y recarga. Sube memory_limit si journalctl muestra « Allowed memory size exhausted ».

5. Detrás de Cloudflare

Comprueba si el servidor de origen responde en directo: curl -I https://IP-DEL-SERVIDOR -H 'Host: example.com' -k. Si responde, puede que el firewall bloquee los rangos de direcciones de Cloudflare, o que el registro DNS en Cloudflare apunte a una IP antigua.

Si el problema está en tu proveedor de hosting

En un hosting compartido no puedes reiniciar PHP-FPM. Envía esto a tu proveedor de hosting:

Hola, mi sitio example.com devuelve « 502 Bad Gateway » desde aproximadamente las 14:30 (UTC). Una comprobación desde fuera lo confirma; no he modificado nada por mi parte. ¿Pueden revisar los procesos de PHP y el servidor web de mi cuenta e indicarme cuándo volverá el sitio?

Para que no vuelva a pasar

Un 502 es casi siempre un backend detenido o saturado, y las dos cosas se ven antes de que los visitantes lo noten: un servicio PHP-FPM parado, una memoria que escasea, un disco que se llena. El monitoring de servidores con el agente de servidor señala exactamente eso desde dentro; las comprobaciones desde fuera atrapan el 502 en cuanto aparece.

¿Caído? Intervenimos. En tu propio servidor o en un hosting compartido con acceso SSH, la intervención rápida reinicia el servicio detenido si su prueba de configuración es correcta, a precio fijo; si la causa es más profunda, la intervención a fondo se encarga del resto, en bloques de 15 minutos, las 24 horas, todos los días.