504 Gateway Timeout: Bedeutung und Lösung

Was der Fehler bedeutet

Beim 504 gibt der Webserver vorne (nginx, Apache, ein Load Balancer, ein CDN) die Anwendung dahinter auf. Die Anfrage wurde weitergereicht, das Backend hat angefangen zu arbeiten, und der Zeitgeber vorne lief ab, bevor eine Antwort kam. Der Unterschied zum 502 Bad Gateway: Das Backend ist erreichbar, es ist nur zu langsam. Übliche Zeitgeber sind 60 Sekunden in nginx (fastcgi_read_timeout, proxy_read_timeout), 60 Sekunden in Apache (ProxyTimeout) und 100 Sekunden bei Cloudflare, die du im kostenlosen Tarif nicht ändern kannst.

Den Timeout zu erhöhen ist selten die Lösung. Irgendetwas dauert zu lange, und dieses Etwas musst du finden.

Häufige Ursachen

1. Eine langsame Datenbankabfrage. Ein WordPress-Plugin, das bei jedem Seitenaufruf Zeilen in einer riesigen Tabelle zählt, ein fehlender Index, eine wp_options-Tabelle voller abgelaufener Transients. Jede Anfrage wartet, und unter Last addieren sich die Wartezeiten.
2. Ein externer Aufruf hängt. Die Anwendung ruft einen Zahlungsanbieter, einen Mail-Dienst, eine Wetter-API oder einen Lizenzserver auf, und dieser Dienst ist langsam oder down. Ohne eigenen Timeout wartet deine Seite mit.
3. Zu wenige Worker. Alle PHP-FPM-Worker stecken in langsamen Anfragen; neue warten in der Schlange, bis der Webserver vorne aufgibt. Von außen sieht das wie ein Timeout aus, obwohl jede einzelne Anfrage schnell wäre.
4. Cron oder Backup im Vordergrund. Ein Backup-Plugin, ein Import, eine Sitemap mit 50.000 URLs: innerhalb einer Web-Anfrage erzeugt, sprengen sie jeden Timeout.
5. Festplatten-I/O oder Swap. Dem Server geht der Arbeitsspeicher aus, er swappt, alles wird zehnmal langsamer. Erkennbar an hoher Last bei niedriger CPU-Auslastung.
6. Netz zwischen vorne und hinten. Ein Load Balancer in einem Rechenzentrum, das Backend in einem anderen, eine Firewall, die Pakete still verwirft. Selten, aber ein 504 bei jeder Anfrage mit untätigem Backend deutet darauf.

Wenn du Besucher bist

Nach einer Minute neu laden. Ist die Website eher langsam als down, probier eine andere Seite; der Timeout hängt vielleicht an einer einzelnen schweren Seite.

Wenn es deine Website ist: zuerst prüfen

Lass den Website-Down-Checker laufen: Er meldet Statuscode und Antwortzeit von außen. Eine Website, die heute in 30 Sekunden antwortet, zeigt morgen unter Last einen 504.

Auf deinem eigenen Server findest du so heraus, wo die Zeit bleibt:

# stauen sich Worker?
sudo tail -n 30 /var/log/nginx/error.log | grep -E 'timed out|timeout'

# was tut PHP gerade? (braucht pm.status_path im Pool)
curl -s 'http://127.0.0.1/fpm-status?full' | grep -E 'state|request URI|duration' | head -40

# MySQL/MariaDB: welche Abfragen laufen, und wie lange schon?
sudo mysql -e 'SHOW FULL PROCESSLIST;'

# Speicher und Swap
free -m
vmstat 1 5

Eine Prozessliste voll mit derselben Abfrage oder si/so-Spalten in vmstat, die nicht null sind, nennen die Ursache.

Lösungen auf deinem eigenen Server

1. Slow-Query-Log einschalten und die Abfrage reparieren

SET GLOBAL slow_query_log = 1;
SET GLOBAL long_query_time = 2;
SET GLOBAL slow_query_log_file = '/var/log/mysql/slow.log';

Nach ein paar Minuten listet sudo mysqldumpslow -s t /var/log/mysql/slow.log | head die schlimmsten Abfragen. Ergänze den fehlenden Index oder finde das Plugin, das die Abfrage stellt, und ersetze es. Bei WordPress ist eine aufgeblähte Optionstabelle ein Klassiker:

wp transient delete --all
wp db query "SELECT option_name, LENGTH(option_value) AS size FROM wp_options WHERE autoload='yes' ORDER BY size DESC LIMIT 20;"

Alles im Bereich von Hunderten Kilobyte, das bei jeder Anfrage automatisch geladen wird, ist ein Kandidat zum Entfernen.

2. Externen Aufrufen einen Timeout geben

Jeder HTTP-Aufruf deiner Anwendung braucht einen eigenen Timeout, kürzer als der des Webservers. In PHP mit cURL: CURLOPT_CONNECTTIMEOUT 5 und CURLOPT_TIMEOUT 10. In WordPress nimmt wp_remote_get() ein Argument timeout; viele Plugins lassen den Standard und warten ewig. Ist ein Fremddienst down, soll die Seite abgespeckt erscheinen (das Formular ohne die Live-Versandkosten), nicht sterben.

3. Lange Arbeit aus der Anfrage herausnehmen

Backups, Importe, Exporte, große Sitemaps und Mailversand gehören in einen Cronjob oder eine Warteschlange, nicht in einen Seitenaufruf. Bei WordPress den Pseudo-Cron abschalten und den echten einrichten:

// wp-config.php
define('DISABLE_WP_CRON', true);

# crontab -e
*/5 * * * * cd /var/www/example.com && wp cron event run --due-now >/dev/null 2>&1

4. Timeouts anpassen, mit Bedacht

Braucht eine einzelne Seite berechtigt länger (ein Admin-Export, ein Bericht), erhöhe den Timeout nur für diese Location, nicht global:

location = /wp-admin/export.php {
    include snippets/fastcgi-php.conf;
    fastcgi_pass unix:/run/php/php8.3-fpm.sock;
    fastcgi_read_timeout 300;
}

Apache mit PHP-FPM: ProxyTimeout 300 in einem <Location>-Block. PHP selbst hat max_execution_time; setz es auf denselben Wert, sonst bricht PHP zuerst ab und du bekommst einen 500 statt des 504. Dann sudo nginx -t && sudo systemctl reload nginx.

5. Swappen beenden

ps aux --sort=-%mem | head

Wenn PHP-FPM-Worker je 150 MB brauchen und du 30 davon auf einem 4-GB-Server laufen lässt, geht die Rechnung nicht auf. Senk pm.max_children, gib mehr Speicher, oder repariere das Plugin, das den Speicher frisst. Ein Server, der nicht swappt, ist ein Server, dessen 504 größtenteils verschwinden.

6. Cachen

Ein Seiten-Cache (nginx FastCGI-Cache, ein WordPress-Caching-Plugin, Varnish) liefert wiederkehrende Besucher aus, ohne PHP oder die Datenbank anzufassen. Die meisten 504 unter Last verschwinden, sobald Startseite und Top-Seiten aus dem Cache kommen.

Wenn es ein Problem deines Hosters ist

Im Shared Hosting kannst du langsame Abfragen und Plugins beheben, aber nicht die Timeouts des Servers oder die Last der Nachbarn. Schick deinem Hoster:

Guten Tag, meine Website example.com liefert seit etwa 16:00 Uhr (UTC) „504 Gateway Timeout“. Seiten, die bisher in unter zwei Sekunden luden, laufen jetzt in den Timeout. Ich habe nichts geändert. Könnten Sie prüfen, ob der Datenbankserver oder der PHP-Pool meines Kontos überlastet ist oder ob ein anderes Konto auf dem Server hohe Last erzeugt, und mir sagen, was Sie finden?

Damit es nicht wieder passiert

Ein 504 ist eine langsame Website, die noch langsamer wurde, und Antwortzeit lässt sich lange vor dem Timeout messen. Website-Prüfungen zeichnen die Antwortzeit jeder Prüfung auf; setz einen Alarm darauf, und du siehst den Trend Wochen, bevor Besucher einen Fehler sehen. Der Server-Agent ergänzt Last, Speicher und Swap aus dem Server heraus. Auf deinem eigenen Server findet der Intensiveingriff die langsame Abfrage oder den hängenden Aufruf und behebt ihn, im 15-Minuten-Takt abgerechnet, Preis vor dem Auftrag.