Shopware Message Queue hängt
Hintergrundaufgaben werden nicht abgearbeitet, E-Mails kommen verspätet an oder Indexierungen bleiben unvollständig. Diese Anleitung zeigt, wie Queue-Worker, Transportwege, fehlgeschlagene Nachrichten, Cronjobs, Prozesslimits und Logdateien systematisch geprüft werden.
Asynchrone Aufgaben bleiben liegen oder werden nur bei geöffneter Shopware-Administration verarbeitet.
Kein laufender CLI-Worker, falscher Receiver, fehlerhafter Cronjob oder eine wiederholt scheiternde Nachricht.
Warteschlangen nicht pauschal in der Datenbank leeren. Zuerst Nachricht, Handler und Fehlerursache bestimmen.
Inhaltsverzeichnis
- Bedeutung der Message Queue
- Fehlerbild eingrenzen
- Queue-Worker manuell testen
- Receiver und Version prüfen
- Queue-Statistik anzeigen
- Fehlgeschlagene Nachrichten prüfen
- Scheduled Tasks abgrenzen
- Cronjob oder Dienst prüfen
- Parallele Prozesse kontrollieren
- Speicher und Laufzeit prüfen
- Logs auswerten
- Admin Worker umstellen
- Dauerhaften Betrieb einrichten
- Abschlusskontrolle
1. Was die Shopware Message Queue macht
Shopware verarbeitet verschiedene Aufgaben asynchron. Eine Aktion wird dabei zunächst als Nachricht in eine Warteschlange geschrieben und anschließend durch einen Worker abgearbeitet. Dadurch müssen aufwendige Prozesse nicht vollständig innerhalb eines einzelnen Browseraufrufs abgeschlossen werden.
Zu den möglichen Queue-Aufgaben gehören unter anderem Indexierungen, Exporte, Aufgaben von Erweiterungen und – abhängig von der Konfiguration – auch der E-Mail-Versand.
Die Warteschlange speichert oder transportiert Nachrichten. Der Worker liest diese Nachrichten und führt den zuständigen Handler aus. Eine gefüllte Queue ist daher nicht automatisch ein Fehler; problematisch wird sie, wenn Nachrichten dauerhaft nicht verarbeitet werden.
| Bestandteil | Aufgabe |
|---|---|
| Nachricht | Beschreibt eine auszuführende Hintergrundaufgabe. |
| Transport | Speichert oder übermittelt Nachrichten, standardmäßig häufig über die Datenbank. |
| Receiver | Bezeichnet die Warteschlange, aus der ein Worker Nachrichten liest. |
| Handler | Enthält die eigentliche Verarbeitung einer bestimmten Nachricht. |
| Worker | Ruft Nachrichten ab und führt die zugehörigen Handler aus. |
| Failure Transport | Nimmt Nachrichten auf, die nach mehreren Versuchen weiterhin fehlschlagen. |
2. Fehlerbild zuerst eingrenzen
- Werden Aufgaben nur verzögert oder überhaupt nicht ausgeführt?
- Funktioniert die Verarbeitung nur bei geöffneter Administration?
- Bleiben Indexierungen oder Produktaktualisierungen unvollständig?
- Fehlen E-Mails oder werden sie erst nach einem manuellen CLI-Aufruf versendet?
- Ist nur eine bestimmte Erweiterung betroffen?
- Trat der Fehler nach einem Shopware-Update auf?
- Wurde der Cronjob noch mit dem alten Receiver default eingerichtet?
- Beendet sich der Worker wegen Speicher- oder Zeitlimits?
Während Importen, Indexierungen oder größeren Änderungen kann die Queue vorübergehend wachsen. Entscheidend ist, ob die Anzahl wieder sinkt und ob die fachlichen Aufgaben abgeschlossen werden.
3. Queue-Worker manuell testen
In das Shopware-Verzeichnis wechseln
cd /pfad/zum/shopware-verzeichnisAktuelle Receiver testweise verarbeiten
bin/console messenger:consume async low_priority --time-limit=60 --memory-limit=512M/usr/bin/php bin/console messenger:consume async low_priority --time-limit=60 --memory-limit=512MAusgabe beobachten
Der Worker zeigt während der Verarbeitung Fehler und gegebenenfalls bearbeitete Nachrichtentypen an. Bleibt die Konsole zunächst ruhig, bedeutet das nicht zwingend einen Fehler: Möglicherweise wartet der Worker lediglich auf neue Nachrichten.
Dann funktionieren Transport und Handler grundsätzlich. Die Ursache liegt wahrscheinlich beim automatischen Start des Workers, beim Cronjob oder beim Prozessmanager.
Die konkrete Exception ist für die weitere Diagnose entscheidend. Ausgabe sichern, Shopware-Logs prüfen und den betroffenen Nachrichtentyp beziehungsweise die zugehörige Erweiterung bestimmen.
4. Richtigen Receiver für die Shopware-Version verwenden
Seit Shopware 6.5 werden für den regulären Queue-Worker die Receiver async und low_priority verwendet. Ein alter Cronjob mit default muss nach einem entsprechenden Versionswechsel geprüft werden.
| Shopware-Version | Typischer Befehl |
|---|---|
| Shopware 6.5 und neuer | messenger:consume async low_priority |
| Ältere Versionen vor 6.5 | messenger:consume default |
Verfügbare Optionen des Befehls anzeigen
bin/console messenger:consume -hErweiterungen oder individuelle Installationen können zusätzliche Transporte verwenden. In diesem Fall müssen die tatsächlich konfigurierten Receiver und der zuständige Worker gemeinsam geprüft werden.
5. Anzahl wartender Nachrichten anzeigen
Mit der Messenger-Statistik lässt sich prüfen, ob Nachrichten in einem oder mehreren Transporten warten.
bin/console messenger:stats/usr/bin/php bin/console messenger:statsErgebnis richtig bewerten
- Steigt die Anzahl dauerhaft weiter an?
- Sinkt sie während eines laufenden Workers?
- Ist nur low_priority betroffen?
- Gibt es Nachrichten im Failure Transport?
- Wächst die Queue nur während eines bekannten Imports?
Eine einzelne Zahl sagt wenig über den Zustand aus. Die Statistik vor, während und nach einem Worker-Lauf vergleichen und zusätzlich prüfen, ob die zugehörige Funktion im Shop ausgeführt wurde.
6. Fehlgeschlagene Nachrichten prüfen
Nachrichten, die auch nach Wiederholungsversuchen nicht verarbeitet werden können, können im Failure Transport landen. Diese Nachrichten sollten zuerst angezeigt und analysiert werden.
Fehlgeschlagene Nachrichten anzeigen
bin/console messenger:failed:showFür Details zu einer konkreten Nachricht kann die in der Ausgabe angezeigte ID verwendet werden:
bin/console messenger:failed:show MESSAGE_ID -vvNachricht nach Fehlerbehebung erneut versuchen
bin/console messenger:failed:retry MESSAGE_IDNachricht nur bewusst entfernen
bin/console messenger:failed:remove MESSAGE_IDEine fehlgeschlagene Nachricht darf erst entfernt werden, wenn klar ist, welche fachliche Aufgabe damit verloren geht oder bereits anderweitig ausgeführt wurde. Vorher Ursache beheben und einen erneuten Versuch bevorzugen.
Scheitert der zugrunde liegende Handler weiterhin, erzeugt ein massenweiser Retry nur zusätzliche Last und neue Fehlversuche.
7. Scheduled Tasks als Ursache abgrenzen
Scheduled Tasks planen wiederkehrende Aufgaben ein. Die Message Queue verarbeitet anschließend viele der erzeugten Nachrichten. Beide Prozesse müssen daher unabhängig geprüft werden.
Scheduled Tasks anzeigen
bin/console scheduled-task:listScheduled Tasks testweise starten
bin/console scheduled-task:run --time-limit=60Danach den Queue-Worker erneut ausführen. Wird eine Aufgabe erst durch diese Reihenfolge erledigt, fehlte entweder der Scheduled-Task-Runner, der Queue-Worker oder beides.
Die vollständige Prüfung ist in der Anleitung Shopware Scheduled Tasks funktionieren nicht beschrieben.
8. Cronjob oder Prozessmanager prüfen
Cronjobs des aktuellen Benutzers anzeigen
crontab -lQueue-Worker testweise mit Logdatei starten
* * * * * cd /pfad/zum/shopware-verzeichnis && /usr/bin/php bin/console messenger:consume async low_priority --time-limit=55 --memory-limit=512M >> /pfad/zum/shopware-verzeichnis/var/log/message-queue-cron.log 2>&1Ausgabe kontrollieren
tail -n 200 var/log/message-queue-cron.log- Stimmt der absolute PHP-Pfad?
- Stimmt das Shopware-Hauptverzeichnis?
- Verwendet der Cronjob die richtige PHP-Version?
- Darf der Cronjob-Benutzer die Shopware-Dateien lesen und in var schreiben?
- Erlaubt der Hoster eine minütliche Ausführung?
- Wird der Prozess vom Hosting vorzeitig beendet?
Der Pfad /usr/bin/php und das Shopware-Verzeichnis müssen zur tatsächlichen Hosting-Umgebung passen.
9. Laufende und parallele Worker kontrollieren
Mehrere Worker können bei größeren Shops sinnvoll sein. Unkontrolliert gestartete Cronjobs können jedoch immer neue Prozesse erzeugen, obwohl vorherige Worker noch laufen.
Laufende Worker anzeigen
ps aux | grep "messenger:consume" | grep -v grepWorker kontrolliert nach aktueller Nachricht stoppen
bin/console messenger:stop-workersLaufende Worker erhalten ein Stoppsignal und beenden sich nach der aktuell verarbeiteten Nachricht. Ein Prozessmanager muss sie danach bei Bedarf neu starten.
Endet eine lange Nachricht erst nach Ablauf des Zeitlimits, kann der nächste Cronlauf bereits einen weiteren Worker starten. Für kontrollierte Prozessanzahlen sind Supervisor oder systemd meist geeigneter.
10. Speicher, Laufzeit und Serverressourcen prüfen
CLI-PHP-Version prüfen
/usr/bin/php -vPHP-Speicherlimit anzeigen
/usr/bin/php -r "echo ini_get('memory_limit'), PHP_EOL;"Freien Speicherplatz prüfen
df -h- Ausreichendes PHP-Memory-Limit für große Indexierungen
- Genügend freier Festplattenspeicher
- Keine dauerhafte CPU-Überlastung
- Keine durch den Hoster erzwungenen kurzen Prozesslimits
- Keine abweichende, inkompatible CLI-PHP-Version
- Ausreichende Datenbankressourcen und freie Verbindungen
Speicher- und Zeitlimits nur erhöhen, wenn die Verarbeitung grundsätzlich korrekt ist. Eine Exception im Handler muss fachlich behoben werden.
11. Shopware- und Server-Logs auswerten
Vorhandene Shopware-Logs anzeigen
ls -lah var/log/Aktuelle Produktionseinträge lesen
tail -n 200 var/log/prod-*.logNach Queue-Fehlern suchen
grep -RiE "messenger|queue|transport|handler|failed|exception|memory|timeout|lock" var/log/ | tail -n 250| Fehlerhinweis | Mögliche Ursache |
|---|---|
| No transport supports the given receiver | Falscher oder nicht konfigurierter Receiver |
| No handler for message | Fehlender Handler, inkompatible Erweiterung oder unvollständiges Update |
| Allowed memory size exhausted | Speicherlimit für die Nachricht zu niedrig |
| Maximum execution time exceeded | Worker oder Hosting beendet den Prozess zu früh |
| Deadlock oder Lock wait timeout | Parallele Datenbankzugriffe oder lange Transaktionen |
| Connection refused oder connection lost | Datenbank, Redis, RabbitMQ oder anderer Transport nicht erreichbar |
| Class not found | Plugin-Dateien, Autoloader oder Versionsstand inkonsistent |
12. Admin Worker und CLI-Worker richtig konfigurieren
Standardmäßig kann Shopware Nachrichten über die geöffnete Administration verarbeiten. Für Produktionssysteme ist ein serverseitiger CLI-Worker zuverlässiger, weil er unabhängig von angemeldeten Backend-Benutzern läuft.
Der Admin Worker sollte erst deaktiviert werden, nachdem der CLI-Worker und die Scheduled Tasks nachweislich automatisch funktionieren.
shopware:
admin_worker:
enable_admin_worker: falseLäuft kein funktionierender CLI-Worker, bleiben nach der Deaktivierung des Admin Workers sämtliche davon abhängigen Hintergrundaufgaben liegen.
13. Queue-Worker dauerhaft betreiben
Bei kleinen Installationen kann ein begrenzter Cronjob ausreichen. Für kontrollierte Worker-Anzahlen, automatische Neustarts und dauerhafte Überwachung sind Supervisor oder systemd meist geeigneter.
Cronjob-Beispiel für Shopware 6.5 und neuer
* * * * * cd /pfad/zum/shopware-verzeichnis && /usr/bin/php bin/console messenger:consume async low_priority --time-limit=55 --memory-limit=512M >> /dev/null 2>&1Scheduled Tasks zusätzlich starten
* * * * * cd /pfad/zum/shopware-verzeichnis && /usr/bin/php bin/console scheduled-task:run --time-limit=55 >> /dev/null 2>&1Bei einer individuellen Worker-Konfiguration muss auch festgelegt sein, wie fehlgeschlagene Nachrichten überwacht und bearbeitet werden. Eine dauerhaft wachsende Fehlerwarteschlange darf nicht unbemerkt bleiben.
Mehr Worker sind nicht automatisch besser. Nachrichtentypen, Datenbankleistung, Speicherverbrauch und mögliche Sperren bestimmen, wie viele parallele Prozesse sinnvoll sind.
14. Abschlusskontrolle
- messenger:consume startet ohne Exception.
- Für Shopware 6.5 und neuer werden async low_priority verwendet.
- Die Queue-Anzahl sinkt während der Verarbeitung.
- Fehlgeschlagene Nachrichten wurden einzeln geprüft.
- Nachrichten wurden erst nach Fehlerbehebung erneut gestartet.
- Scheduled Tasks werden separat ausgeführt.
- Der Cronjob verwendet den richtigen PHP-Pfad.
- Das Shopware-Arbeitsverzeichnis ist korrekt.
- Worker überlappen sich nicht unkontrolliert.
- Speicher- und Zeitlimits sind ausreichend.
- Die Shopware-Logs enthalten keine neue Queue-Exception.
- Die fachlich erwartete Aufgabe wurde vollständig ausgeführt.
- Die Verarbeitung funktioniert ohne geöffnete Administration.
- Die Queue bleibt auch nach mehreren Intervallen stabil.
Die Störung ist behoben, wenn neue Nachrichten automatisch verarbeitet werden, die Warteschlange nicht dauerhaft wächst und keine wiederholten Fehler im Failure Transport entstehen.
Häufige Fragen
Warum wird die Queue nur bei geöffneter Administration verarbeitet?
Dann arbeitet wahrscheinlich der Admin Worker, während kein serverseitiger CLI-Worker zuverlässig läuft. Für den Produktionsbetrieb sollte die Verarbeitung unabhängig von einer Backend-Sitzung erfolgen.
Welcher Queue-Befehl gilt ab Shopware 6.5?
Für aktuelle Versionen werden normalerweise die Receiver async und low_priority verarbeitet.
Was bedeutet eine Nachricht im Failure Transport?
Die Nachricht konnte auch nach Wiederholungsversuchen nicht erfolgreich verarbeitet werden. Vor einem Retry oder Entfernen muss die konkrete Exception geprüft werden.
Darf die Message Queue direkt in der Datenbank geleert werden?
Nicht als allgemeine Fehlerbehebung. Dadurch können noch notwendige Aufgaben unwiederbringlich verloren gehen. Zuerst Worker, Failure Transport, Handler und Logs untersuchen.
Warum beendet sich der Worker nach 60 Sekunden?
Das ist bei Verwendung von --time-limit=60 beabsichtigt. Ein Cronjob oder Prozessmanager muss den Worker anschließend erneut starten.
Reicht ein Queue-Worker ohne Scheduled Tasks?
Nein. Scheduled Tasks planen wiederkehrende Aufgaben ein, während der Queue-Worker die erzeugten Nachrichten verarbeitet. Für einen stabilen Shopbetrieb müssen beide Prozesse funktionieren.
Sollten mehrere Worker parallel laufen?
Das hängt von Nachrichtenmenge, Nachrichtentypen und Serverleistung ab. Mehrere Worker können die Verarbeitung beschleunigen, aber auch Datenbanksperren und Ressourcenverbrauch erhöhen.
Verwandte Shopware-Anleitungen
Die Shopware Message Queue hängt weiterhin?
Ich prüfe Queue-Worker, Receiver, Failure Transport, Scheduled Tasks, Cronjobs, Erweiterungen und Server-Logs direkt in der bestehenden Shopware-Installation.
Technische Prüfung anfragen