504 Gateway Timeout

Was dieser Fehler bedeutet und wie du ihn erkennst

• Der Browser zeigt nach einer Wartezeit 504 Gateway Timeout an, statt sofort einen Fehler auszugeben.
• Berichte, Massenimporte, Exporte, Bildverarbeitung oder komplexe Suchvorgänge schlagen fehl, während einfache Seiten weiterhin funktionieren.
• Die Fehler treten häufiger auf, wenn die Anwendung ausgelastet ist oder sich Anfragen in einer Warteschlange befinden.
• Das Backend antwortet bei einem direkten Test, aber dieselbe Anfrage läuft über einen Proxy, ein CDN oder einen Load Balancer in ein Timeout.
• Gateway-Logs zeigen, dass eine Upstream-Anfrage lange läuft, bevor der 504 zurückgegeben wird.
• Die Anwendung kann die Verarbeitung fortsetzen, nachdem der Browser das Timeout erhalten hat. Bei einer Wiederholung können dadurch doppelte oder abgebrochene Vorgänge entstehen.

Hauptursachen nach Wahrscheinlichkeit

1. Langsame oder blockierte Datenbankabfragen: Fehlende Indizes, wachsende Tabellen, ineffiziente Abfragen und konkurrierende Sperren können dazu führen, dass die Anwendung länger als das Gateway-Limit wartet.
2. Überlastung oder Warteschlangen im Backend: Anfragen warten möglicherweise auf Anwendungs-Worker, Datenbankverbindungen, CPU, Arbeitsspeicher oder andere begrenzte Ressourcen.
3. Ein tatsächlich lang laufender synchroner Vorgang: Große Exporte, Importe, Berichte oder Dateiverarbeitungen können sinnvoll sein, sich aber für eine normale Seitenanfrage nicht eignen.
4. Eine langsame nachgelagerte API oder ein langsamer Webhook: Die Anwendung wartet möglicherweise auf einen anderen Dienst, bevor sie antworten kann.
5. Zu restriktive Proxy- oder Server-Timeouts: Nginx, Apache, ein CDN oder ein Load Balancer beendet das Warten möglicherweise, bevor die Anwendung fertig ist.
6. Netzwerkprobleme zwischen Gateway-Schichten: Latenz, sporadischer Paketverlust oder Routingfehler sind bei Bereitstellungen über mehrere Server oder Regionen wahrscheinlicher, insbesondere wenn die Anwendungsdauer die Verzögerung nicht erklärt.

So behebst du den Fehler

1. Die fehlerhafte Anfrage und ihre Dauer identifizieren

Prüfen Sie die Zugriffs- und Anwendungslogs des Gateways auf die Anfrage, die den 504 verursacht hat. Notieren Sie Route oder Benutzeraktion, Zeitstempel, Antwortdauer, Status und ob alle Anfragen fehlschlagen oder nur ein bestimmter Vorgang betroffen ist.

Wenn nur Berichte, Importe, Exporte oder komplexe Suchvorgänge fehlschlagen, beginnen Sie mit diesem Vorgang, statt den Vorfall als vollständigen Serverausfall zu behandeln.

2. Backend und vollständigen Anfragepfad vergleichen

Vergleichen Sie mit einer autorisierten und sicheren Testanfrage die direkte Antwortzeit des Backends mit der Antwortzeit derselben Anfrage über Proxy, CDN oder Load Balancer.

• Eine sowohl direkt als auch über das Gateway langsame Antwort weist auf die Anwendung, die Datenbank, die Kapazität oder eine Abhängigkeit hin.
• Eine direkte schnelle Antwort bei gleichzeitig fehlschlagender Anfrage über den Proxy weist auf ein Timeout der Vermittlungsschicht, ein Routingproblem oder ein Netzwerkproblem zwischen Gateway und Backend hin.

Umgehen Sie keine Zugriffskontrollen der Produktionsumgebung und senden Sie nicht nur zu Testzwecken eine zustandsverändernde Anfrage.

3. Datenbankdauer und Wartezeiten auf Sperren untersuchen

Aktivieren oder prüfen Sie die Diagnosefunktionen der Datenbank für langsame Abfragen und Wartezeiten auf Sperren entsprechend den betrieblichen Richtlinien Ihrer Datenbankplattform. Suchen Sie nach Abfragen, die annähernd so lange wie das aktive Gateway-Timeout oder länger laufen.

Prüfen Sie fehlende Indizes, ineffiziente Joins oder Filter, das Tabellenwachstum und konkurrierende Sperren. Optimieren Sie die Abfrage, reduzieren Sie die verarbeitete Datenmenge oder fügen Sie nur dann einen Index hinzu, wenn bestätigt ist, dass er die gemessene Engstelle behebt. Stimmen Sie Änderungen am Schema oder an Indizes mit dem Datenbankverantwortlichen ab, da sie Ressourcen verbrauchen und gleichzeitig laufende Workloads beeinflussen können.

Erhöhen Sie das Timeout nicht einfach, um eine Abfrage zu verschleiern, die eigentlich schnell abgeschlossen sein sollte.

4. Backend-Kapazität und Warteschlangen prüfen

Prüfen Sie Anwendungs-, Webserver- und Systemmetriken während des Fehlers auf erschöpfte Worker, wartende Anfragen, Limits für Datenbankverbindungen, CPU- oder Speicherdruck sowie andere Ressourcenengpässe.

Wenn Anfragen auf verfügbare Kapazität warten, beheben Sie zuerst diese Engstelle, bevor Sie Timeouts verlängern. Änderungen an Kapazität oder Prozesseinstellungen können die Stabilität des Dienstes beeinflussen. Nehmen Sie solche Änderungen daher nur mit der erforderlichen betrieblichen Genehmigung und nach dem vorgesehenen Change-Prozess vor.

5. Lang laufende Aufgaben in einen Hintergrundjob verschieben

Verwenden Sie für Importe, Exporte, Berichtserstellung, E-Mail-Verarbeitung und ähnliche Aufgaben einen Hintergrundjob, sofern die Anwendung dies unterstützt. Die ursprüngliche Anfrage sollte die Verarbeitung starten oder in die Warteschlange stellen, während eine separate Statusansicht oder Benachrichtigung den Fortschritt und den Abschluss meldet.

So müssen Browserverbindung, Gateway-Worker und Anwendungsanfrage nicht für die gesamte Dauer des Vorgangs geöffnet bleiben. Stellen Sie vor der Aktivierung dieses Musters sicher, dass der Job geeignete Wiederholungs- und Schutzmechanismen gegen doppelte Übermittlungen besitzt.

6. Nginx-Timeout-Einstellungen sorgfältig prüfen

Wenn Nginx als Gateway fungiert, prüfen Sie die zutreffenden Einstellungen proxy_read_timeout und proxy_connect_timeout im relevanten server- oder location-Block. Stellen Sie fest, welche Schicht das Timeout erzwingt, bevor Sie Änderungen vornehmen.

Erhöhen Sie ein Timeout nur, wenn der Vorgang erwartungsgemäß länger dauert, das Backend gesund ist und die zusätzliche Nutzung von Verbindungen und Workern akzeptabel ist. Konfigurationsänderungen erfordern eine entsprechende Genehmigung. Validieren Sie die Konfiguration nach dem Speichern und laden Sie Nginx gemäß Ihrem normalen Bereitstellungsverfahren neu. Wiederholen Sie anschließend den zuvor fehlgeschlagenen Vorgang. Kombinieren Sie in einer ungeplanten Änderung keinen Serviceneustart mit schreibgeschützten Diagnosen.

7. Apache-Proxy-Einstellungen prüfen

Bei Apache mit mod_proxy prüfen Sie die zutreffenden Einstellungen Timeout und ProxyTimeout. Wenn große Uploads beteiligt sind, prüfen Sie außerdem das relevante Verhalten von mod_reqtimeout.

Wenden Sie nach Möglichkeit mit Genehmigung und einem Rollback-Plan die kleinste sichere Änderung für die betroffene Route oder den betroffenen Vorgang an. Testen Sie anschließend mit derselben Anfrage erneut und stellen Sie sicher, dass längere Wartezeiten keine Worker oder Verbindungen erschöpfen.

8. Verhalten von CDN und Load Balancer prüfen

Wenn die Website Cloudflare oder ein anderes CDN beziehungsweise einen Load Balancer verwendet, prüfen Sie die Gateway-Timeouts, das Origin-Routing, den Zustand und die planabhängige Konfiguration dieses Dienstes. Eine Vermittlungsschicht kann ein Limit erzwingen, das in der verfügbaren Konfiguration nicht erhöht werden kann.

Wenn der Origin länger als dieses Limit benötigt, optimieren Sie den Vorgang oder verschieben Sie ihn in eine asynchrone Verarbeitung, statt sich auf eine längere Browseranfrage zu verlassen.

9. Langsame Aufrufe von Drittanbietern isolieren

Messen Sie jeden externen API- oder Webhook-Aufruf separat. Setzen Sie, sofern unterstützt, ein kürzeres internes Timeout für eine Abhängigkeit, behandeln Sie Fehler ausdrücklich und geben Sie einen ausstehenden oder wiederholbaren Status zurück, wenn die Verarbeitung später abgeschlossen werden kann.

Verhindern Sie, dass eine unzuverlässige Abhängigkeit das gesamte Gateway-Timeout verbraucht. Stellen Sie vor dem Hinzufügen automatischer Wiederholungen sicher, dass diese begrenzt und sicher sind.

10. Die Behebung überprüfen

Wiederholen Sie genau die Seitenaktion oder Anfrage, die zuvor fehlgeschlagen ist. Stellen Sie sicher, dass sie innerhalb des aktiven Gateway-Timeouts abgeschlossen wird, und prüfen Sie anschließend die Logs, damit das Backend keine abgebrochenen, doppelten oder ungewöhnlich lange laufenden Vorgänge anhäuft. Testen Sie über den vollständigen Produktionspfad und nicht nur direkt gegen das Backend.

Vorbeugung und Überprüfung der Lösung

• Verwenden Sie Hintergrundjobs für Importe, Exporte, Berichtserstellung, E-Mail-Verarbeitung und andere Aufgaben, die länger als eine normale Seitenanfrage dauern können.
• Prüfen Sie Indizes und Abfragepläne für Datenbankoperationen hinter Seiten, bei denen mit wachsender Datenmenge häufig Timeouts auftreten.
• Überwachen Sie Anfragedauer, Zeit in der Warteschlange, Datenbankdauer, Workernutzung und Dauer von Abhängigkeiten getrennt.
• Legen Sie Proxy- und Anwendungs-Timeouts bewusst für den langsamsten legitimen Vorgang fest, während die Timeouts für Abhängigkeiten von Drittanbietern begrenzt bleiben.
• Testen Sie kritische Vorgänge über den vollständigen Produktionspfad einschließlich CDN oder Load Balancer und nicht nur gegen den Origin.
• Gestalten Sie Wiederholungen und erneute Übermittlungen sicher, damit ein Gateway-Timeout keine doppelten Jobs oder Transaktionen erzeugt.
• Wiederholen Sie nach einer Änderung genau den Vorgang, bei dem das Timeout auftrat, und stellen Sie sicher, dass sich keine übermäßige Arbeit in der Warteschlange ansammelt.

Häufig gestellte Fragen