Zurück zum Blog

502 Bad Gateway: Ursachen und Lösungen für Nginx

502 Bad Gateway? So lesen Sie das Nginx-Fehlerlog, starten PHP-FPM oder Ihre App, korrigieren Port oder Socket, erhöhen pm.max_children, prüfen Cloudflare.

Nodesty-Team9 Min. LesezeitHosting
Der Schriftzug 502 Bad Gateway mit nginx, upstream und PHP-FPM auf dunklem Nodesty-Hintergrund

Ein 502 Bad Gateway bedeutet, dass ein Server vor Ihrer Website, meist Nginx, ein CDN oder ein Load Balancer, die Anfrage an die Anwendung dahinter weitergegeben und keine brauchbare Antwort zurückbekommen hat. Der Proxy funktioniert; das Problem liegt fast immer beim Upstream: PHP-FPM, einer Node.js- oder Python-Anwendung oder einem Docker-Container, der ausgefallen ist, an einer anderen Adresse lauscht oder unter Last abstürzt.

In dieser Anleitung zeigen wir, wie Sie die genaue Ursache im Nginx-Fehlerlog finden und die häufigsten Fälle beheben: einen gestoppten Dienst, falschen Port oder Socket, einen erschöpften PHP-FPM-Pool, Speichermangel, zu große Header, SELinux, Cloudflare und Docker. Einen Überblick über alle Statuscodes gibt unsere Anleitung zu HTTP-Fehlercodes.

Erster Schritt: das Nginx-Fehlerlog lesen

Der Browser zeigt nur „502 Bad Gateway“, doch Nginx schreibt den Grund in sein Fehlerlog. Nachdem Sie sich per SSH mit Ihrem Server verbunden haben, sehen Sie sich die letzten Zeilen an:

sudo tail -n 50 /var/log/nginx/error.log

Hat eine Website in ihrem Server-Block eine eigene error_log-Zeile, prüfen Sie stattdessen diese Datei. Laden Sie die Seite im Browser neu, während sudo tail -f /var/log/nginx/error.log läuft, dann sehen Sie die neue Zeile sofort. Diese Meldungen begegnen Ihnen am häufigsten:

Meldung in error.logWas sie meist bedeutet
connect() failed (111: Connection refused)Auf dem Port lauscht nichts: Die App läuft nicht
connect() to unix:/run/php/php8.3-fpm.sock failed (2: ...)Der Socket fehlt: falscher Pfad oder FPM gestoppt
connect() to unix:... failed (13: Permission denied)Nginx darf den Socket nicht öffnen, oder SELinux blockt
upstream prematurely closed connectionDie App ist beim Antworten abgestürzt oder beendet worden
upstream sent too big headerAntwort-Header größer als der Puffer von Nginx
upstream timed out (110: Connection timed out)Die App ist zu langsam; Nginx liefert hier 504

Jede Zeile enthält außerdem upstream: "...", also die genaue Adresse, die Nginx erreichen wollte. Vergleichen Sie sie mit der Adresse, an der Ihre Anwendung tatsächlich lauscht.

Die Anwendung oder PHP-FPM läuft nicht

Das ist mit Abstand die häufigste Ursache. Bei PHP-Websites prüfen Sie den PHP-FPM-Dienst (ersetzen Sie 8.3 durch Ihre Version):

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

Unter AlmaLinux heißt der Dienst einfach php-fpm. Bei einer Node.js- oder Python-Anwendung prüfen Sie den Prozessmanager, den Sie verwenden:

pm2 status
pm2 logs --lines 50
sudo systemctl status myapp
sudo journalctl -u myapp -n 50

Startet der Dienst nicht, zeigt sein eigenes Log den Grund: einen Syntaxfehler, eine fehlende Umgebungsvariable oder einen bereits belegten Port (siehe Port bereits belegt). Damit die Anwendung nach einem Absturz oder Neustart von selbst wieder hochfährt, betreiben Sie sie als Dienst, wie in systemd-Service erstellen beschrieben. Eine funktionierende Einrichtung für eine Python-App hinter Gunicorn zeigt unsere Anleitung Python-App deployen.

Falscher Upstream-Port oder Socket-Pfad

Läuft die Anwendung, Nginx bekommt aber weiterhin Connection refused, klopft Nginx an der falschen Tür. Vergleichen Sie die Adresse in proxy_pass oder fastcgi_pass mit dem, was tatsächlich lauscht:

sudo ss -tlnp | grep -E 'node|python|php|gunicorn'
ls -l /run/php/

Ein Klassiker ist das PHP-Upgrade: Die neue Version legt /run/php/php8.4-fpm.sock an, die Website zeigt aber noch auf php8.3-fpm.sock, den es nicht mehr gibt, und im Log steht (2: No such file or directory). Passen Sie die fastcgi_pass-Zeile an den neuen Socket an, wie in PHP-Version ändern gezeigt.

Eine leise Falle ist auch localhost. Löst proxy_pass http://localhost:3000; zur IPv6-Adresse ::1 auf, die App lauscht aber nur auf 127.0.0.1, wird die Verbindung abgelehnt. Schreiben Sie die Adresse ausdrücklich:

location / {
    proxy_pass http://127.0.0.1:3000;
}

Permission denied am Socket

(13: Permission denied) an einem PHP-FPM-Socket bedeutet, dass der Nginx-Benutzer den Socket nicht öffnen darf. Unter Ubuntu und Debian läuft Nginx als www-data, und die Pool-Datei /etc/php/8.3/fpm/pool.d/www.conf sollte dazu passen:

listen = /run/php/php8.3-fpm.sock
listen.owner = www-data
listen.group = www-data
listen.mode = 0660

Unter AlmaLinux läuft Nginx als nginx, und der Standard-Pool lauscht auf /run/php-fpm/www.sock; achten Sie darauf, dass nginx in listen.acl_users in /etc/php-fpm.d/www.conf steht. Starten Sie PHP-FPM nach jeder Änderung neu.

PHP-FPM gehen die Worker aus: pm.max_children

Treten 502-Fehler nur unter Last auf, sehen Sie in das PHP-FPM-Log:

sudo grep max_children /var/log/php8.3-fpm.log

Eine Zeile wie WARNING: [pool www] server reached pm.max_children setting (5), consider raising it bedeutet, dass alle PHP-Worker beschäftigt waren. Der Standardwert 5 unter Debian und Ubuntu ist für eine gut besuchte Website zu niedrig. Ermitteln Sie, wie viel Speicher ein Worker im Schnitt belegt:

ps --no-headers -o rss -C php-fpm8.3 | awk '{s+=$1} END {print s/NR/1024 " MB"}'

Teilen Sie den RAM, den Sie PHP geben können, durch diesen Wert. Bei 4 GB für PHP und Workern mit rund 80 MB ist etwa 50 ein vernünftiges Limit. Tragen Sie es in die Pool-Datei ein und starten Sie PHP-FPM neu:

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

Setzen Sie den Wert nicht höher, als Ihr RAM zulässt: Zu viele Worker drängen den Server in den Swap oder in den Speichermangel, und das führt direkt zur nächsten Ursache.

Die Anwendung wird bei Speichermangel beendet

Geht dem Server der RAM aus, beendet der OOM-Killer des Kernels den Prozess mit dem größten Speicherverbrauch, oft PHP-FPM-Worker, Node.js oder die Datenbank. Nginx sieht dann eine geschlossene Verbindung oder einen abgelehnten Port. So prüfen Sie, ob das passiert ist:

sudo dmesg -T | grep -i -E 'out of memory|killed process'
free -h

Finden Sie Treffer, senken Sie den Speicherverbrauch (weniger Worker, niedrigere Limits), richten Sie als Puffer Swap ein, wie in Linux Swap einrichten beschrieben, oder wechseln Sie zu einem Paket mit mehr RAM. Was die Ressourcen auffrisst, finden Sie mit unserer Anleitung Server langsam?.

upstream sent too big header

Anwendungen, die große Cookies oder viele Header setzen (manche WordPress-Plugins, Authentifizierungs-Proxys), können den Standardpuffer von Nginx sprengen. Vergrößern Sie ihn im location-Block, je nachdem, ob Sie proxy_pass oder PHP-FPM verwenden:

# Reverse Proxy (proxy_pass)
proxy_buffer_size 16k;
proxy_buffers 8 16k;

# PHP-FPM (fastcgi_pass)
fastcgi_buffer_size 32k;
fastcgi_buffers 16 16k;

Timeouts: 502 oder 504?

Ist die Anwendung zu langsam, liefert Nginx nach Ablauf von proxy_read_timeout (standardmäßig 60 Sekunden) ein 504 Gateway Timeout. Für lange Vorgänge wie Exporte können Sie den Wert für eine einzelne Location mit proxy_read_timeout 300s; erhöhen (für PHP fastcgi_read_timeout). Eine langsame Anfrage kann trotzdem mit 502 enden: Beendet PHPs max_execution_time oder das request_terminate_timeout des Pools den Worker zuerst, schreibt Nginx upstream prematurely closed connection ins Log. Die eigentliche Lösung ist, den langsamen Code oder die Abfrage zu verbessern; längere Timeouts verdecken das Problem nur.

SELinux unter AlmaLinux

Unter AlmaLinux und anderen RHEL-basierten Systemen erlaubt SELinux Nginx standardmäßig keine Netzwerkverbindungen zu einer Anwendung. Im Log steht dann connect() to 127.0.0.1:3000 failed (13: Permission denied), obwohl die App läuft. Erlauben Sie es dauerhaft:

sudo setsebool -P httpd_can_network_connect 1

Schalten Sie SELinux dafür nicht komplett ab; dieser eine Schalter genügt.

Apache mod_proxy

Nutzen Sie Apache als Reverse Proxy, finden Sie das Log unter /var/log/apache2/error.log (unter AlmaLinux /var/log/httpd/error_log). Eine Meldung wie AH01102: error reading status line from remote server bedeutet, dass das Backend ungültig geantwortet oder die Verbindung geschlossen hat. Beachten Sie, dass Apache ein Backend, das Verbindungen ablehnt, meist mit 503 statt 502 meldet. Die Prüfungen sind dieselben: Läuft das Backend, und stimmen Adresse und Port in ProxyPass?

502-Fehler bei Cloudflare

Steht Ihre Website hinter Cloudflare, sehen Sie sich zuerst die Fehlerseite an. Eine Cloudflare-gebrandete 502- oder 504-Seite deutet auf ein Problem im Netzwerk von Cloudflare hin; prüfen Sie deren Statusseite. Eine schlichte Seite mit nginx am unteren Rand stammt von Ihrem Ursprungsserver, und alle Schritte oben gelten. Die eigenen Codes von Cloudflare sind genauer: 521 bedeutet, dass Ihr Webserver die Verbindung abgelehnt hat, 522, dass die Verbindung in einen Timeout lief, oft weil eine Firewall die IP-Bereiche von Cloudflare blockiert.

Um den Ursprungsserver ohne Cloudflare zu testen, schicken Sie die Anfrage direkt an seine IP-Adresse:

curl -I --resolve ihredomain.de:443:203.0.113.10 https://ihredomain.de

Docker: Containername, Port und Netzwerk

Läuft Nginx in einem Container, meint 127.0.0.1 den Nginx-Container selbst, nicht Ihre App. Hängen Sie beide in dasselbe Docker-Netzwerk und verwenden Sie den Servicenamen und den Port, auf dem die App im Container lauscht:

proxy_pass http://app:3000;

Die App muss im Container auf 0.0.0.0 lauschen, nicht nur auf 127.0.0.1. Ob der Container läuft, prüfen Sie mit docker ps und docker logs app. Nginx löst den Namen beim Start auf; wird der App-Container mit neuer IP neu erstellt, laden Sie Nginx ebenfalls neu. Läuft Nginx auf dem Host, veröffentlichen Sie den Port (zum Beispiel -p 127.0.0.1:3000:3000) und leiten auf 127.0.0.1:3000 weiter. Die Docker-Grundlagen finden Sie in Docker installieren.

Shared Hosting

Im Shared Hosting verwalten Sie weder den Proxy noch PHP-FPM; ein 502 entsteht dort meist, weil Ihr Konto seine Ressourcenlimits (CPU, Speicher oder Entry Processes) erreicht, oder durch ein Problem beim Anbieter. Prüfen Sie die Seite Resource Usage in cPanel und das Fehlerlog, deaktivieren Sie kürzlich installierte Plugins und wenden Sie sich bei anhaltendem Fehler mit dem genauen Zeitpunkt an den Support.

Nginx testen und neu laden

Testen Sie nach jeder Konfigurationsänderung, bevor Sie neu laden, damit ein Tippfehler nicht alle Websites lahmlegt:

sudo nginx -t
sudo systemctl reload nginx

Schnelle Checkliste

PrüfungBefehl oder Ort
Was sagt Nginx?sudo tail -n 50 /var/log/nginx/error.log
Läuft das Backend?systemctl status php8.3-fpm, pm2 status
Stimmt die Adresse?ss -tlnp, ls /run/php/ und proxy_pass
Ist der FPM-Pool voll?max_children in /var/log/php8.3-fpm.log
Wurde etwas beendet?Killed process in dmesg -T
Nur AlmaLinuxsetsebool -P httpd_can_network_connect 1
Hinter Cloudflare?Gebrandete Seite oder Origin-Seite, curl --resolve
Konfiguration gültig?nginx -t, dann systemctl reload nginx

Neu in der Nginx-Konfiguration? Unsere Anleitung Nginx installieren erklärt Server-Blöcke und die Reverse-Proxy-Einrichtung von Anfang an.

502-Fehler beheben bei Nodesty

Auf den Nodesty AMD Ryzen 9 9950X vServern haben Sie vollen Root-Zugriff: Sie lesen jedes Log, stimmen PHP-FPM und Nginx ab und starten Dienste selbst neu, auf NVMe-Speicher und mit kostenlosen täglichen Backups, die 7 Tage aufbewahrt werden. Möchten Sie keinen Server verwalten, betreibt das Webhosting von Nodesty Ihre Websites auf Servern mit AMD Ryzen 9 7900, dem Webserver LiteSpeed, NVMe-Speicher und cPanel oder DirectAdmin, wo Sie Ressourcennutzung und Fehlerlogs direkt im Panel sehen.

Häufig gestellte Fragen

Was bedeutet 502 Bad Gateway?

Ein Server, der als Gateway oder Proxy arbeitet, meist Nginx, ein CDN wie Cloudflare oder ein Load Balancer, hat die Anfrage an den Server dahinter weitergereicht und keine gültige Antwort erhalten. Der Proxy selbst funktioniert; die Anwendung, PHP-FPM oder der Container dahinter ist ausgefallen, nicht erreichbar oder hat etwas geantwortet, mit dem der Proxy nichts anfangen kann.

Liegt ein 502-Fehler an mir als Besucher?

Nein. Ein 502 ist ein serverseitiger Fehler; den Cache zu leeren oder den Browser zu wechseln, hilft selten. Als Besucher können Sie nur ein paar Minuten warten und es erneut versuchen. Gehört Ihnen die Website, verrät das Fehlerlog des Webservers, warum der Proxy die Anwendung nicht erreicht hat.

Was ist der Unterschied zwischen 502 und 504?

Bei einem 502 hat der Proxy überhaupt keine gültige Antwort bekommen, etwa weil die Verbindung abgelehnt wurde oder die Anwendung mitten in der Anfrage abgestürzt ist. Bei einem 504 hat die Anwendung die Verbindung angenommen, aber nicht innerhalb des Timeouts geantwortet. Ein 502 deutet meist auf etwas Ausgefallenes oder falsch Konfiguriertes hin, ein 504 auf etwas zu Langsames.

Warum tritt der 502-Fehler nur zeitweise auf?

Sporadische 502-Fehler bedeuten meist, dass dem Backend unter Last die Kapazität ausgeht. PHP-FPM erreicht sein Limit pm.max_children, die Anwendung wird bei Speichermangel beendet und neu gestartet, oder ein Container startet in einer Schleife neu. Prüfen Sie das PHP-FPM-Log und dmesg auf Out-of-Memory-Meldungen zu den Zeitpunkten des Fehlers.

Schadet ein 502-Fehler der SEO?

Ein kurzer Ausfall nicht. Suchmaschinen werten 5xx-Fehler als vorübergehend und versuchen es später erneut. Liefert eine Website aber tagelang 502, wird seltener gecrawlt, und Seiten können irgendwann aus dem Index fallen. Wiederkehrende 502-Fehler sollten Sie daher an der Ursache beheben statt mit Neustarts.

Ich bekomme 502 im Shared Hosting. Was kann ich tun?

Im Shared Hosting verwalten Sie Webserver und PHP-FPM nicht selbst; die Ursache ist meist ein Ressourcenlimit Ihres Kontos oder ein Problem beim Anbieter. Prüfen Sie die Ressourcennutzung im Control Panel und das Fehlerlog, deaktivieren Sie ein kürzlich installiertes Plugin und wenden Sie sich mit dem Zeitpunkt des Fehlers an den Support.

Nodesty

Über den Autor

Nodesty-Team · Infrastruktur und Support

Das Nodesty-Team betreibt unsere Server, unser Netzwerk und unseren DDoS-Schutz im Alltag und beantwortet Support-Anfragen rund um die Uhr. Diese Ratgeber entstehen aus dieser Arbeit.

Verwandte Artikel

Starte deinen Server jetzt.

Erstellen, wachsen und skalieren Sie Ihre Projekte grenzenlos auf der Premium-Infrastruktur von Nodesty.

                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                                                                                                                            
                                                                                                                             ············································                                                   
                                                ··································································································..........···························                                     
                                       ················..........................................................................................................................··············                             
                                  ·············.................::::::::::::::::::::::::::::::::::::::::::::::....................:::::::::::::::::::::::::::::::::::::::................···········                        
                             ············................:::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::::............·········                     
                         ············.................:::::::::::::::::::::::::::::::::::::::::::::::::::------------::::::::::::::::::::::::::::::----------------:::::::::::::::::::::..........········                  
                    ············......................::::::::::::::::::::::::::::::::::::------------------------------------------------------------------------------------:::::::::::::.........········                
                ··········.............................................::::::::::::::::::-------------==========================================-----------------------------------:::::::::::........·······               
             ········..................:.....................................::::::::::--------=======+++++++++++++++++++++++++++++++++++++=========================------------------::::::::::.......·······              
           ······.........::::::::::::::::::::................................:::::::-----=====++++xxxxxx**************************xxxxxxxxx++++++++++++++===================------------::::::::.......·······             
          ·····.......:::::::::::::::::::::::::::.............................:::::----===+++xxx****%%%%&&&&&&#############&&&&&&&%%%%%*******xxxxxxxx++++++++++++++==============----------:::::::......······             
         ····......::::::::-------------:::::::::::..........................::::---===+++xx***%%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@####&&&&&%%%%*******xxxxxxxxx+++++++++++++===========--------::::::......·····             
        ····.....:::::::--------------------:::::::::.......................::::---===++xxx**%%&&&###@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&%%%%%********xxxxxxxxxxx++++++++++++========------::::::.....······            
        ····.....:::::--------------------------::::::::....................::::---===++xx***%%&&&####@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@@###&&&&&%%%%%**********xxxxxxxxxxxxx+++++++++=======------:::::.....·····            
        ····....::::::-------=============---------:::::::::................:::::---===+++xx***%%%&&&#####@@@@@@@@@@@@@@@@@@@@@@@@@#####&&&&&%%%%%%*************xxxxxxxxxxxxxx+++++++++======-----:::::....·····            
         ····....:::::-------================---------:::::::::...............:::::----===++++xxx***%%%%&&&&&&#################&&&&&&%%%%%%%*******************xxxxxxxxxxxxxxxxx++++++++======----:::::....·····            
         ·····....:::::--------=================---------::::::::::..............:::::::-----====+++++xxxxxx**************************xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx++++++++=====-----::::....·····            
          ·····.....:::::--------=================----------:::::::::::.................:::::::::-------=============++++++++++++++++++++++++++++++++++++xxxxxxxxxxxxxxxxxxxxxxx++++++++======-----::::....·····            
            ·····.....:::::::----------===========-------------::::::::::::.........................::::::::::::::::::------------------=============+++++++++++++++++++++++++++++++++=======-----::::.....·····            
              ······......:::::::---------------------------------:::::::::::::........................................:::::::::::::::-----------============+++++++++++++++++++++========------:::::.....·····             
                 ······........:::::::::---------------------------:::::::::::::::::...........................................:::::::::::::------------=============================--------::::::.....······              
                    ·········.........:::::::::::::::-------------::::::::::::::::::::::::.......................................::::::::::::::::--------------------------------------::::::::......·······                
                          ··········............::::::::::::::::::::::::::::::::::::::::::::::::::................................::::::::::::::::::::::::::-------------:::::::::::::::.........········                   
                                  ············..................:::::::::::::::::::::::::::::::::::::::::::.........................:::::::::::::::::::::::::::::::::::::................···········                        
                                             ················.............................................................................................................·················                                 
                                                           ······················................................................................···························                                                
                                                                               ·········································································