502 Bad Gateway: de oorzaak vinden en oplossen

Wat de fout betekent

Een 502 is het antwoord van een server die werkt. De webserver vooraan (nginx, Apache, een load balancer of een CDN zoals Cloudflare) heeft het verzoek ontvangen, doorgegeven aan de applicatie erachter (PHP-FPM, een Node.js- of Python-proces) en niets bruikbaars teruggekregen: verbinding geweigerd, afgebroken of een onleesbaar antwoord. De “gateway” is de server vooraan; “bad” is wat er van achteren terugkwam. Een 502 zegt dus twee dingen: vooraan werkt alles; achteraan is iets gestopt of kapot.

Veelvoorkomende oorzaken

1. Het applicatieproces draait niet. PHP-FPM is gecrasht of gestopt, het Node.js-proces is dood, de container is afgesloten. De server vooraan krijgt helemaal geen verbinding.
2. De applicatie zit vol. Alle workers van PHP-FPM zijn bezet, de wachtrij is vol, nieuwe verbindingen worden geweigerd. Vaak na een piek in bezoekers of door een trage databasequery die elke worker blokkeert.
3. Verkeerde socket of poort. Na een wissel van PHP-versie wijst nginx nog naar php8.2-fpm.sock, terwijl de nieuwe pool luistert op php8.4-fpm.sock.
4. Te korte time-outs. De backend antwoordt, maar te laat voor de webserver. Sommige configuraties melden dat als 502, andere als 504 Gateway Timeout.
5. De backend stuurt te grote headers of een ongeldig antwoord. Typisch voor frameworks die de cookies volproppen; nginx logt dan upstream sent too big header.
6. De CDN bereikt je server niet. Een 502-pagina met het logo van Cloudflare betekent dat Cloudflare niets van je server heeft gekregen: firewall, verkeerd IP-adres na een verhuizing of een server die uitstaat.

Als je bezoeker bent

Een 502 op een site die niet van jou is, los je aan jouw kant niet op. Herlaad na een minuut; blijft het, dan kan alleen de beheerder van de site iets doen. Is het je eigen site, lees dan verder.

Als het je eigen site is: eerst controleren

Is hij down voor iedereen? Open de Website down checker: de HTTP-code van buitenaf, en wie er antwoordde, de CDN of de server.

Shared hosting of websitebouwer? Daar is een 502 bijna altijd een probleem van de hostingprovider (een volle PHP-pool op een gedeelde server). Ga door naar het kant-en-klare bericht verderop.

Eigen server: maak verbinding via SSH en lees wat de webserver zegt.

# nginx: de laatste fouten, de nieuwste onderaan
sudo tail -n 50 /var/log/nginx/error.log

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

Typische regels en wat ze betekenen:

• connect() to unix:/run/php/php8.3-fpm.sock failed (2: No such file or directory): PHP-FPM draait niet, of het pad naar de socket klopt niet.
• connect() failed (111: Connection refused) while connecting to upstream: niemand luistert op de poort van de backend.
• upstream prematurely closed connection: de backend is tijdens het antwoorden gecrasht, vaak door een fatale PHP-fout of geheugengebrek.
• upstream sent too big header: verhoog fastcgi_buffer_size in nginx.
• (11: Resource temporarily unavailable): alle workers van PHP-FPM zijn bezet.

Oplossingen op je eigen server

1. De gestopte dienst starten

# welke PHP-FPM-versie gebruik je?
systemctl list-units --type=service | grep -E 'php|fpm'

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

# Node.js- of Python-applicaties onder systemd
sudo systemctl restart mijn-app

Start hij niet, dan staat de reden in journalctl -u php8.3-fpm -n 50. Het vaakst: een volle schijf (df -h) en, direct daarna, een syntaxfout in een pool (sudo php-fpm8.3 -t).

2. Socket of poort corrigeren

Vergelijk het adres waarmee nginx verbinding maakt met het adres waarop PHP-FPM luistert:

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

Die twee moeten gelijk zijn. Test na elke wijziging voordat je herlaadt:

sudo nginx -t && sudo systemctl reload nginx

Met Apache en mod_proxy_fcgi geldt dezelfde regel voor de regel SetHandler "proxy:unix:/run/php/php8.3-fpm.sock|fcgi://localhost"; de test is sudo apachectl configtest.

3. PHP-FPM lucht geven

Meldt het log server reached pm.max_children, verhoog dan de limiet in het poolbestand (/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

Elke worker kost geheugen (bij WordPress vaak 30 tot 80 MB); controleer free -m voordat je verhoogt en zoek de trage query of de plugin die de workers vasthoudt.

4. Buffers verhogen voor grote headers

In het server-blok van nginx:

fastcgi_buffers 16 16k;
fastcgi_buffer_size 32k;
proxy_buffers 8 16k;
proxy_buffer_size 32k;

5. Het WordPress-geval

Een 502 direct na de update van een plugin of thema: PHP struikelt bij elk verzoek over een fatale fout of over het geheugen. Hernoem de map van de plugin via SFTP of SSH (wp-content/plugins/naam-plugin naar naam-plugin.uit) of voer wp plugin deactivate naam-plugin uit, en herlaad. Verhoog memory_limit als journalctl “Allowed memory size exhausted” laat zien.

6. Achter Cloudflare

Controleer of de origin-server rechtstreeks antwoordt: curl -I https://IP-VAN-DE-SERVER -H 'Host: example.com' -k. Antwoordt hij, dan blokkeert de firewall misschien de IP-reeksen van Cloudflare, of wijst het DNS-record bij Cloudflare naar een oud IP-adres; de kennisbank Cloudflare 521 en 522 loopt de stappen door.

Ligt het bij je hostingprovider?

Op shared hosting kun je PHP-FPM niet herstarten. Stuur dit naar je hostingprovider, met het tijdstip en de exacte foutmelding:

Goedemiddag, mijn website example.com geeft sinds ongeveer 14:30 (UTC) “502 Bad Gateway”. Een controle van buitenaf bevestigt dit; ik heb zelf niets gewijzigd. Kunt u de PHP-processen en de webserver van mijn account controleren en mij laten weten wanneer de site weer online is?

Zo gebeurt het niet opnieuw

Een 502 is bijna altijd een gestopte of volle backend, en allebei zijn ze te zien voordat bezoekers er iets van merken: een gestopte PHP-FPM-dienst, geheugen dat opraakt, een schijf die volloopt. Server monitoring met de serveragent meldt precies dat van binnenuit; de controles van buitenaf vangen de 502 op zodra hij verschijnt.

Down? Wij fixen het. Op je eigen server of op shared hosting met SSH-toegang herstart de Quick Fix, de automatische reparatie tegen een vaste prijs, de gestopte dienst als de configuratietest slaagt; zit de oorzaak dieper, dan regelt de Deep Fix de rest, per blok van 15 minuten, 24 uur per dag, ook in het weekend; de schatting is de bovengrens.