502 Bad Gateway bij nginx oplossen
Een 502 zegt niet dat nginx stuk is: het zegt dat nginx het antwoord van je applicatie niet kreeg. Dat maakt de zoekruimte klein — het zit in de applicatie, in de verbinding ertussen, of in een timeout.
Loop je hier nu tegenaan?
Bel of mail en leg het voor. Neem ik niet op, stuur dan even een mail.
Herken je dit?
- De site geeft 502 Bad Gateway, soms wel en soms niet.
- Het begon na een deploy, een update of een herstart.
- Alleen zware pagina's geven 502, lichte pagina's werken.
- Het gebeurt vooral op drukke momenten.
- Na een wijziging aan de proxyconfiguratie is het begonnen.
Waar het meestal aan ligt
In verreweg de meeste gevallen is het één van deze. Loop ze in deze volgorde na.
De applicatie achter de proxy draait niet
PHP-FPM, Node, Gunicorn of een container is gestopt of niet herstart na een update. In het nginx-errorlog staat dan connect() failed of no live upstreams.
Verkeerde socket of poort
De fastcgi_pass of proxy_pass wijst naar een socketpad of poort die niet meer bestaat, bijvoorbeeld na een PHP-versie-upgrade waarbij het pad meeverandert.
Timeouts bij langdurige verzoeken
Een verzoek dat langer duurt dan proxy_read_timeout of fastcgi_read_timeout wordt door nginx afgekapt met een 504. Krijg je een 502 na een vaste tijd, dan kapt de backend zelf af, bijvoorbeeld PHP-FPM met request_terminate_timeout of Gunicorn met --timeout. Typisch bij imports, rapporten en uploads.
Buffers te klein voor grote headers
Grote response-headers van de backend (veel Set-Cookie, SSO-tokens) passen niet in de standaardbuffer en geven upstream sent too big header. Verhoog proxy_buffer_size, of fastcgi_buffer_size bij PHP. Anders faalt precies de ingelogde gebruiker.
Rechten op de socket
nginx draait als een andere gebruiker dan de applicatie. Klopt de eigenaar of de modus van de Unix-socket niet, dan mag nginx er niet bij en krijg je permission denied.
Resources en processlimieten
PHP-FPM met een pm.max_children die te laag is, of een applicatie die door de OOM-killer wordt beëindigd. Onder belasting krijg je dan intermitterende 502's.
Wat ik als eerste check
Doe deze stappen zelf, of bel en dan lopen we ze samen door.
- 1
Lees het nginx-errorlog
tail -50 /var/log/nginx/error.log. Bij een 502 staat daar bijna altijd een concrete reden: connection refused, permission denied, prematurely closed, too big header of no live upstreams. Staat er niks, dan komt de 502 waarschijnlijk van de backend zelf of van een proxy daarachter. Dat bepaalt alles wat daarna komt. - 2
Controleer of de applicatie draait
systemctl status php8.3-fpm,docker compose psof het equivalent. Niet draaien is de meest voorkomende oorzaak en meteen zichtbaar. - 3
Test de upstream direct
curl -v http://127.0.0.1:3000/ofcgi-fcginaar de socket. Werkt de applicatie direct wel, dan ligt het tussen nginx en de applicatie; werkt hij ook direct niet, dan ligt het in de applicatie. - 4
Kijk naar de timing
Komt de 502 steeds na precies dezelfde tijd, 30 of 60 seconden bijvoorbeeld? Dan kapt de backend het verzoek af en is het geen crash. (Kapt nginx zelf af, dan zie je een 504.) Dat verschil scheelt uren zoeken in de verkeerde richting.
- 5
Controleer de socketrechten
ls -l /run/php/en vergelijk eigenaar en modus met de gebruiker waaronder nginx draait. Na een upgrade wijzigt dat pad geregeld mee. - 6
Controleer geheugen en OOM
dmesg -T | grep -i oomenfree -m. Wordt je applicatieproces weggeschoten door de kernel, dan is de 502 een symptoom van geheugendruk.
Het errorlog doet het werk
Bij een 502 hoef je niet te raden. nginx schrijft bij elke mislukte upstream-poging een regel met de reden erbij: connect() failed (111: Connection refused), upstream prematurely closed connection, upstream sent too big header, permission denied. Die vier of vijf varianten dekken vrijwel alles.
Wat tijd kost, is dat mensen in het accesslog kijken (waar alleen de 502 zelf staat) in plaats van in het errorlog. Eén commando scheelt daar een middag.
Snel weer in de lucht
Bij een site die plat ligt, gaat het eerst om online komen en daarna om de oorzaak. Bel, dan kijk ik in de logs mee en zeg wat er moet gebeuren — ook als je het zelf uitvoert.
Veelgestelde vragen
- Wat betekent 502 precies?
- Dat nginx als tussenpersoon geen geldig antwoord kreeg van de dienst erachter. nginx zelf werkt dus: je moet verder kijken naar de applicatie of naar de verbinding daarnaartoe. Het errorlog van nginx noemt bijna altijd de precieze reden.
- Het gebeurt maar af en toe. Hoe vind ik dat?
- Intermitterende 502's zijn bijna altijd resources of timeouts: te weinig workers, geheugendruk of langzame verzoeken. Correleer de tijdstippen uit het accesslog met belasting en met de OOM-meldingen in dmesg, dan zie je het patroon.
- Kan ik de timeout gewoon verhogen?
- Dat kan en soms is het de juiste keuze, bijvoorbeeld bij een import die nu eenmaal lang duurt. Maar vaak is het een pleister: als een pagina 60 seconden nodig heeft, is de echte vraag waarom. Ik zeg eerlijk wanneer verhogen prima is en wanneer het iets verbergt.
- Kun je dit op korte termijn oppakken?
- Ja. Met toegang tot de server begin ik bij het errorlog, want dat geeft de richting al aan.
Verwante problemen
Docker-container start niet of crasht direct
Container die direct stopt, exit code 137 of 125, data die weg is na een update en containers die elkaar niet vinden. Dit check ik als eerste.
[TLS-certificaat]SSL-certificaat verlopen of vernieuwt niet
Certificaat verlopen, of een Let's Encrypt-vernieuwing die stil faalt. De oorzaken, de eerste checks en hoe je voorkomt dat het nog eens gebeurt.
[Boot en recovery]Server start niet meer op
Een server die na een update of herstart niet meer boot: kernel, fstab, volle schijf of bootloader. Zo kom je via rescue mode weer binnen.
Wil je dit bespreken?
Bel of mail met je vraag. Neem ik niet op, stuur dan even een mail.
Terug naar Linux-serverbeheer en hosting