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 en leg het voor. Vaak is in tien minuten duidelijk waar het aan ligt. Bellen mag direct. Mail beantwoord ik meestal dezelfde werkdag.
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 afgekapt en levert een 502 of 504. Typisch bij imports, rapporten en uploads.
Buffers te klein voor grote headers
Grote cookies of headers (bijvoorbeeld met SSO-tokens) passen niet in de standaardbuffers. Verhoog proxy_buffer_size en proxy_buffers, 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 altijd een concrete reden: connection refused, permission denied, timeout of no live upstreams. 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 na precies 60 seconden? Dan is het een timeout en geen crash. 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 timed out, 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, en meestal is het snel. Met toegang tot de server is een 502 vrijwel altijd binnen een uur herleid, omdat het errorlog de richting al aangeeft.
Verwante problemen
Docker-container start niet of crasht direct
Container die direct stopt, exit code 137 of 125, volumes die leeg zijn na een herstart 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.
Zelf geen tijd of geen zin om te blijven zoeken?
Ik kijk mee, zeg eerlijk wat er aan de hand is en los het op. Bellen mag direct. Mail beantwoord ik meestal dezelfde werkdag.
Terug naar Linux serverbeheer en troubleshooting