Een 502 Bad Gateway-fout in Nginx betekent meestal dat Nginx geen geldig antwoord heeft ontvangen van een upstreamserver, zoals PHP-FPM, Node.js of een andere backendapplicatie.
De meest voorkomende oorzaken zijn gestopte applicatieservices, onjuiste upstream-poorten of -sockets en backendprocessen die crashen of verbindingen onverwacht sluiten.
Controleer eerst de foutlogs van Nginx. Daarin staat vaak precies waarom de verbinding is mislukt.
Deze handleiding leidt je door zeven praktische stappen om problemen op te sporen op Linux-servers met Nginx.
Wat veroorzaakt een 502 Bad Gateway-fout in Nginx?
Nginx fungeert vaak als reverse proxy: het stuurt verzoeken door naar backendapplicaties en geeft hun antwoorden terug aan bezoekers.
Als de upstreamservice niet correct reageert, kan Nginx HTTP-statuscode 502 teruggeven.
Veelvoorkomende oorzaken zijn:
- Backendservices die zijn gestopt of gecrasht.
- Onjuiste upstream-IP-adressen, -poorten of Unix-sockets.
- Storingen in PHP-FPM of applicatieprocessen.
- Problemen met toegangsrechten voor sockets.
- Onvoldoende geheugen of schijfruimte.
- Ongeldige of voortijdig gesloten upstreamverbindingen.
Voor de volgende controles heb je SSH-toegang en beheerdersrechten voor je Linux-server nodig.
1. Controleer de foutlogs van Nginx
De foutlogs van Nginx zijn meestal de snelste manier om de oorzaak van een 502-fout te vinden.
Maak via SSH verbinding met je server en voer het volgende uit:
sudo tail -n 50 /var/log/nginx/error.logHiermee worden de laatste 50 logregels weergegeven.
Gebruik het volgende om het probleem live te onderzoeken:
sudo tail -f /var/log/nginx/error.logLaad de getroffen webpagina opnieuw en let op nieuwe meldingen.
| Logmelding | Waarschijnlijke oorzaak |
|---|---|
connect() failed (111: Connection refused) | De backend accepteert geen verbindingen |
No such file or directory | De geconfigureerde upstreamsocket ontbreekt |
Permission denied | Nginx heeft geen toegang tot de socket of bron |
upstream prematurely closed connection | De backend heeft de verbinding onverwacht gesloten |
upstream sent invalid header | De backend heeft ongeldig opgemaakte antwoordheaders teruggestuurd |
In jouw hostingconfiguratie kunnen de logs op een andere locatie staan.
Wijzig de Nginx-instellingen pas als je de waarschijnlijke oorzaak hebt vastgesteld.
2. Controleer of de backendservice actief is
Een 502-fout treedt vaak op doordat de applicatie achter Nginx is gestopt.
Voer voor een applicatieservice die door systemd wordt beheerd het volgende uit:
sudo systemctl status myappVervang myapp door de naam van je eigen service.
Voor applicaties op basis van PHP die PHP-FPM gebruiken, kan de servicenaam er zo uitzien:
sudo systemctl status php8.3-fpmDe geïnstalleerde PHP-versie en de servicenaam kunnen afwijken.
Als de service is uitgevallen, bekijk dan de logs ervan:
sudo journalctl -u myapp -n 50Controleer op crashes, ontbrekende afhankelijkheden, configuratiefouten of problemen door geheugentekort.
Start de service pas opnieuw nadat je het onderliggende probleem hebt vastgesteld en aangepakt.
3. Controleer de upstream-poort of -socket
Nginx moet verzoeken doorsturen naar het juiste backendadres.
Een reverse-proxyconfiguratie kan bijvoorbeeld het volgende bevatten:
location / {
proxy_pass http://127.0.0.1:3000;
}Hiermee krijgt Nginx de opdracht om verzoeken door te sturen naar een HTTP-applicatie die op poort 3000 luistert.
Controleer of er op die poort een proces luistert:
sudo ss -ltnp | grep ':3000'Je kunt een HTTP-backend ook rechtstreeks testen:
curl -i http://127.0.0.1:3000/Als de backend niet beschikbaar is, onderzoek dan de serviceconfiguratie voordat je Nginx wijzigt.
Controleer PHP-FPM-sockets
PHP-FPM gebruikt doorgaans Unix-sockets of TCP-poorten.
Een Nginx-configuratie kan het volgende bevatten:
fastcgi_pass unix:/run/php/php8.3-fpm.sock;Controleer of de geconfigureerde socket bestaat:
ls -l /run/php/Het socketpad moet overeenkomen met de instelling listen van de PHP-FPM-pool en Nginx moet toestemming hebben om verbinding te maken.
Belangrijk: proxy_pass wordt gebruikt voor HTTP-upstreamservers, terwijl fastcgi_pass wordt gebruikt voor FastCGI-services zoals PHP-FPM. Ze zijn niet onderling uitwisselbaar.
4. Controleer het servergeheugen en de schijfruimte
Backendapplicaties kunnen crashen of niet meer reageren als de server zonder beschikbare bronnen komt te zitten.
Controleer het geheugen:
free -hControleer de schijfruimte:
df -hControleer de actieve processen:
topAls een applicatie is beëindigd door geheugentekort, vind je mogelijk relevante meldingen in het systeemjournal:
sudo journalctl -k --since "1 hour ago"Zoek naar gebeurtenissen waarbij het geheugen opraakte of naar meldingen over beëindigde processen.
Als de schijfruimte op is, bepaal dan eerst wat die ruimte in beslag neemt voordat je bestanden verwijdert.
5. Controleer socketrechten en applicatielogs
Soms is de backend actief, maar kan Nginx er niet mee communiceren.
Controleer bij Unix-sockets de eigenaar en toegangsrechten:
ls -l /run/php/Controleer ook de bovenliggende mappen van de socket als de logs een fout met toegangsrechten melden.
De juiste toegangsrechten hangen af van de gebruikersaccount van de Nginx-worker en de configuratie van de backendservice.
Vermijd ruime toegangsrechten zoals chmod 777. Pas in plaats daarvan de configuratie van de betreffende service of pool aan, zodat bevoegde processen toegang hebben tot de socket.
Als de foutlogs melden dat de upstreamserver de verbinding voortijdig heeft gesloten, controleer dan de logs van de backendapplicatie op crashes, uitzonderingen of mislukte verzoeken.
6. Test je Nginx-configuratie
Onjuiste proxy-instellingen of wijzigingen in de configuratie kunnen ook de communicatie met de upstreamserver verstoren.
Controleer de Nginx-configuratie voordat je wijzigingen toepast:
sudo nginx -tAls de test slaagt, laad Nginx dan opnieuw:
sudo systemctl reload nginxDoor Nginx opnieuw te laden, pas je geldige configuratiewijzigingen toe zonder de service onnodig opnieuw te starten.
Als de test mislukt, verhelp dan eerst de gemelde configuratiefout.
Verhoog proxy-time-outs of bufferlimieten niet zomaar. Daarmee los je een gestopte backend, onjuiste socket of geweigerde verbinding niet op.
7. Controleer of de 502-fout is opgelost
Test de getroffen URL nadat je het onderliggende probleem hebt aangepakt:
curl -I https://example.comVervang example.com door je eigen domein.
Een geslaagd verzoek geeft doorgaans een passende HTTP-status terug, zoals 200 OK, hoewel omleidingen en andere geldige antwoorden andere codes kunnen opleveren.
Open de website ook in je browser en bekijk de foutlogs van Nginx opnieuw.
Als de fout terugkeert bij hoge belasting, houd dan de backendservice en het gebruik van serverbronnen in de gaten terwijl je het probleem reproduceert.
Zo voorkom je 502-fouten in Nginx
Niet elke backendstoring is te voorkomen, maar goed serverbeheer beperkt vermijdbare uitval.
- Houd de status van Nginx en backendservices in de gaten.
- Controleer applicatielogs na nieuwe deployments.
- Stel een passend beleid in voor het herstellen van services.
- Houd het gebruik van geheugen, opslagruimte en verbindingen in de gaten.
- Controleer configuratiewijzigingen voordat je ze toepast.
- Test applicaties rechtstreeks voordat je verkeer via Nginx doorstuurt.
Als een applicatie meer serverbronnen nodig heeft, meet dan eerst het werkelijke gebruik voordat je besluit de servercapaciteit uit te breiden.
Veelgestelde vragen
Het betekent dat Nginx als gateway of proxy een ongeldig antwoord van een upstreamserver heeft ontvangen. De oorzaak is vaak een gestopte backendservice of een probleem met de upstreamverbinding.
Niet per se. Een herstart of het opnieuw laden van Nginx verhelpt geen onbeschikbare applicatie, onjuiste backendpoort of ontbrekende PHP-FPM-socket.
Een 502-fout duidt op een ongeldig antwoord van de upstreamserver, terwijl een 504-fout betekent dat de gateway niet binnen de ingestelde time-out een antwoord van de upstreamserver heeft ontvangen.
Ja. Een tekort aan geheugen kan ervoor zorgen dat backendprocessen crashen of worden beëindigd, waardoor Nginx niet meer met ze kan communiceren.
Nee. Ook andere gateways, proxy’s, CDN’s en loadbalancers kunnen HTTP 502-fouten teruggeven.
Conclusie
Het oplossen van een 502 Bad Gateway-fout in Nginx begint met achterhalen waarom de upstreamapplicatie niet correct reageert.
Controleer eerst de foutlogs van Nginx, ga na of de backendservice actief is en verifieer de geconfigureerde poort of socket. Onderzoek daarna eventuele beperkingen van serverbronnen, toegangsrechten en applicatiestoringen.
In de meeste gevallen is het effectiever om de specifieke upstreamstoring te achterhalen dan Nginx herhaaldelijk opnieuw te starten of time-outinstellingen te wijzigen.
