Logo
WP Fix by Blimx

WordPress 502 Bad Gateway — Causas y Arreglos

Actualizado:
ErrorsInfrastructure

Por qué 502 es más difícil que 500

Un 500 te dice que algo dentro de WordPress se rompió. Un 502 te dice que el camino entre el visitante y WordPress se rompió — tu proxy (Nginx, Cloudflare, balanceador de carga) intentó hablar con el upstream de WordPress y no obtuvo nada de vuelta, o obtuvo algo que no pudo parsear.

Como el fallo está en el borde entre dos sistemas, debuggear requiere mirar ambos. Este artículo es el playbook upstream-por-upstream que usamos en cada 502.

El mapa de arquitectura

La mayoría de sitios WordPress modernos tienen esta ruta de petición:

Visitante → Cloudflare → Nginx → PHP-FPM → MySQL

Un 502 significa que una de esas flechas se rompió. Identifica cuál flecha primero, después profundiza en esa capa específica. No reinicies PHP-FPM solo porque alguien dijo que podría ayudar.

Causa 1 — PHP-FPM sin workers

La causa upstream más común. El pool de workers de PHP-FPM está saturado. Las peticiones nuevas hacen cola, eventualmente expiran, Nginx devuelve 502.

Detectar

# Log de Nginx
tail /var/log/nginx/error.log | grep "upstream prematurely closed"

# Estado de PHP-FPM
systemctl status php-fpm
journalctl -u php-fpm -n 50 | grep "max_children"

Si ves server reached pm.max_children setting, esta es tu causa.

Arreglo

Calcula el valor correcto (ver nuestra guía profunda del 500 para la fórmula), configura en /etc/php/8.1/fpm/pool.d/www.conf:

pm = dynamic
pm.max_children = 50
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 15
pm.max_requests = 500

Recarga PHP-FPM:

systemctl reload php-fpm

Causa 2 — Una sola petición lenta bloqueando workers

No tienes muchas peticiones — solo una realmente lenta (un export admin, un import pesado, una reconstrucción de sitemap) que mantiene workers ocupados 60+ segundos. Otras peticiones se apilan detrás, son rechazadas, se vuelven 502s.

Detectar

Mira el slow log de PHP-FPM (habilítalo si no está):

slowlog = /var/log/php-fpm/www.slow.log
request_slowlog_timeout = 10s

Recarga PHP-FPM, reproduce, examina /var/log/php-fpm/www.slow.log.

Arreglo

  • Mueve la operación lenta a un trabajo en segundo plano (Action Scheduler, cron WP-CLI)
  • Usa un pool PHP-FPM separado para peticiones admin para que no puedan matar de hambre al pool del front-end
  • Añade una ruta "long-running" a un pool de workers separado con más memoria y tiempo

Causa 3 — fastcgi_pass equivocado tras actualización de PHP

Subiste PHP de 7.4 a 8.1. La ruta del socket cambió (/var/run/php/php8.1-fpm.sock en lugar de /var/run/php/php7.4-fpm.sock). Nginx aún referencia el socket viejo, que ya no existe.

Detectar

grep fastcgi_pass /etc/nginx/sites-available/*
ls -la /var/run/php/

Si el socket al que Nginx apunta no existe, lo encontraste.

Arreglo

Actualiza la config de Nginx:

location ~ \.php$ {
    fastcgi_pass unix:/var/run/php/php8.1-fpm.sock;
    # ... otras directivas
}

Recarga Nginx:

nginx -t && systemctl reload nginx

Causa 4 — Handshake TLS Cloudflare → origen fallando

El modo SSL de Cloudflare es "Full (strict)" pero tu certificado de origen es self-signed o está expirado. Cloudflare rehúsa conectar; los visitantes ven el 502 con marca Cloudflare.

Detectar

echo | openssl s_client -connect yoursite.com:443 -servername yoursite.com 2>/dev/null | openssl x509 -noout -dates

Revisa la fecha notAfter. Si está pasada, el certificado expiró.

Arreglo

  • Renueva el certificado del origen (Let's Encrypt: certbot renew)
  • O cambia el modo SSL de Cloudflare a "Full" (menos estricto, acepta self-signed)
  • O usa los certificados gratis Origin CA de Cloudflare (15 años de validez)

Causa 5 — Segfault de PHP

Raro pero posible. Una extensión PHP con bugs o un build de PHP crashea a mitad de petición. El worker muere; Nginx obtiene una respuesta incompleta y devuelve 502.

Detectar

journalctl -u php-fpm | grep -i "segfault\|core dumped"
dmesg | grep php-fpm

Si ves mensajes de segfault, esta es la causa.

Arreglo

  • Identifica la extensión que falla (usualmente una extensión PECL custom)
  • Desactívala: phpdismod xdebug o similar
  • Actualiza PHP a la última versión patch
  • Reporta un bug al mantenedor de la extensión

Workaround hasta que esté arreglado:

pm.max_requests = 50

Fuerza reciclaje de worker cada 50 peticiones, limitando el impacto de fugas lentas.

Causa 6 — Presión de memoria causando OOM kills

El OS está matando procesos por presión de memoria. Los workers PHP-FPM son matados a mitad de petición. Los visitantes ven 502.

Detectar

dmesg | grep -i "out of memory\|killed process"
journalctl -k | grep -i oom

Arreglo

  • Identifica el devorador de memoria (a menudo MySQL o un script PHP descontrolado)
  • Añade swap (temporal):
fallocate -l 2G /swapfile
chmod 600 /swapfile
mkswap /swapfile
swapon /swapfile
echo '/swapfile none swap sw 0 0' >> /etc/fstab
  • Largo plazo: añade RAM o divide servicios entre múltiples servidores

El diagnóstico de 502 en 5 minutos

# Paso 1 — confirma de dónde se origina el 502
curl -I https://yoursite.com/  # revisa el header Server

# Paso 2 — log de errores upstream de Nginx
tail -100 /var/log/nginx/error.log

# Paso 3 — estado del pool de workers PHP-FPM
ss -xl | grep php-fpm
curl http://localhost/fpm-status 2>/dev/null

# Paso 4 — eventos recientes de memoria/procesos
dmesg --since "5 min ago" | tail -50
journalctl --since "5 min ago" -u php-fpm

# Paso 5 — ¿Cloudflare u origen?
echo | openssl s_client -connect yoursite.com:443 -servername yoursite.com 2>/dev/null | grep "verify return"

Cada paso acota la causa. Cinco minutos total, causa raíz identificada.

Errores comunes al diagnosticar 502

  • Reiniciar PHP-FPM sin revisar qué estaba pasando — enmascara el síntoma, no aborda la causa
  • Subir `pm.max_children` a un número enorme — eventualmente agota RAM, lo empeora
  • Culpar "al hosting" — el hosting a menudo no tiene nada que ver; tu stack sí
  • Subir `proxy_read_timeout` de Nginx a 600s — enmascara PHP lento, no arregla nada

Cuándo llamar a un especialista

Si has trabajado a través del diagnóstico y el 502 vuelve en horas, el problema es estructural — un plugin lento manteniendo workers, una fuga de memoria en código custom, un mismatch de arquitectura entre PHP-FPM y tu patrón de tráfico. Manejamos estos cada semana.

Soporte de emergencia 502 en minutos. Para emergencias más amplias ve soporte de emergencia WordPress.