NGINX-Fehler und wie man sie behebt

Beim Betrieb einer Website mit NGINX können gelegentlich Fehler auftreten, die den reibungslosen Betrieb der Seite beeinträchtigen. Diese Anleitung behandelt die häufigsten davon — 502 Bad Gateway, 504 Gateway Time-out und 413 Request Entity Too Large — und zeigt Schritt für Schritt, wie sie auf einem VPS oder dedizierten Servern behoben werden können.

502 Bad Gateway

Was es bedeutet: NGINX kann keine Antwort vom Backend erhalten (PHP-FPM, Apache, Node.js, uWSGI usw.).

Häufigste Ursachen:

• Backend-Dienst ist gestoppt oder abgestürzt
• Falscher Socket-Pfad oder falscher Port in der Konfiguration
• Falsche Berechtigungen am Socket
• Zu wenig Arbeitsspeicher oder Worker-Prozesse in PHP-FPM

Behebung:

1. Status von PHP-FPM (oder Ihres Backends) prüfen:

sudo systemctl status php-fpm
# oder für eine bestimmte Version
sudo systemctl status php8.1-fpm

2. Dienst neu starten:

sudo systemctl restart php-fpm
# oder php8.1-fpm

3. Socket-Pfad in den NGINX- und PHP-FPM-Konfigurationen prüfen:

   • NGINX: fastcgi_pass unix:/run/php/php8.1-fpm.sock;
   • PHP-FPM (/etc/php/8.1/fpm/pool.d/www.conf): listen = /run/php/php8.1-fpm.sock

4. Berechtigungen bei Bedarf korrigieren:

sudo chown www-data:www-data /run/php/php8.1-fpm.sock
sudo chmod 660 /run/php/php8.1-fpm.sock

5. NGINX testen und neu laden:

sudo nginx -t && sudo systemctl reload nginx

504 Gateway Time-out

Was es bedeutet: NGINX hat zu lange auf eine Antwort vom Backend gewartet und das Timeout überschritten.
Häufigste Ursachen:

• Langsame PHP-Skript-Ausführung
• Langsame Datenbankabfragen
• Hohe Server-Auslastung

Behebung:

1. Timeouts in der Site-Konfiguration erhöhen (im server- oder location-Block):

proxy_connect_timeout 300s;
proxy_send_timeout 300s;
proxy_read_timeout 300s;
fastcgi_read_timeout 300s;  # für PHP

2. PHP-FPM optimieren (in /etc/php/8.1/fpm/pool.d/www.conf):

pm.max_children = 50          # nach Bedarf erhöhen
pm.start_servers = 10
pm.min_spare_servers = 5
pm.max_spare_servers = 20
request_terminate_timeout = 300

3. Dienste neu starten:

sudo systemctl restart php-fpm
sudo systemctl reload nginx

4. Falls das Problem bei einem bestimmten Skript liegt — DB-Abfragen optimieren oder Caching für rechenintensive Seiten einrichten.

413 Request Entity Too Large

Was es bedeutet: Der Client versucht, eine Datei hochzuladen, die das in NGINX festgelegte Limit überschreitet (Standard: 1 MB).
Häufige Ursachen: Hochladen großer Dateien (Fotos, Videos, Backups, Archive).

Behebung:

1. Limit in der Site-Konfiguration erhöhen (oder in /etc/nginx/nginx.conf im http-Block):

client_max_body_size 64M;  # oder 128M, 512M, 1G usw.

2. NGINX neu laden:

sudo nginx -t && sudo systemctl reload nginx

3. Auch die PHP-Limits in der php.ini erhöhen (/etc/php/8.1/fpm/php.ini):

upload_max_filesize = 64M
post_max_size = 64M

PHP-FPM neu starten:

sudo systemctl restart php-fpm

NGINX korrekt neu laden

• Konfiguration immer zuerst prüfen:

sudo nginx -t

• Graceful Reload (ohne Downtime):

sudo systemctl reload nginx

oder

sudo nginx -s reload

• Vollständiger Neustart (nur wenn Reload nicht hilft):

sudo systemctl restart nginx

Nützliche Hinweise

• Erstellen Sie vor Änderungen immer ein Backup der Konfiguration: sudo cp /etc/nginx/nginx.conf /etc/nginx/nginx.conf.bak
• Prüfen Sie nach Änderungen die Logs: /var/log/nginx/error.log und /var/log/nginx/access.log