← Alle Beiträge

Shopware 6: Class "RelatedWebhooks" not found nach dem Update

Shopware 6: Class "RelatedWebhooks" not found nach dem Update

Das Update ist durch, Storefront und Administration laufen, alles sieht gut aus. Dann stehen im Log plötzlich CRITICAL-Einträge vom Message-Queue-Worker, und zwar mit einer Klasse, von der du noch nie gehört hast. RelatedWebhooks. Kein Plugin, kein eigener Code, sondern ein Shopware-Core-Namespace.

Die gute Nachricht vorweg: Dein Update ist sehr wahrscheinlich nicht kaputt. Der Fehler kommt von einem Prozess, der das Update nicht mitbekommen hat.

Die Fehlermeldung

Meist taucht sie doppelt auf, einmal vom PHP-Error-Handler und einmal vom Console-Command:

CRITICAL: Error thrown while running command "messenger:consume --time-limit=300 --memory-limit=768M async low_priority failed".
Message: "Class "Shopware\Core\Framework\Webhook\Service\RelatedWebhooks" not found"
at /var/www/shop/var/cache/prod_h<hash>/Container<id>/Shopware_Core_KernelProdContainer.php

Dazu kommen je nach Ausgangsversion Varianten, die erst mal gar nicht verwandt aussehen:

Uncaught Error: Class "WebhookManagerGhost<id>" not found
at /var/www/shop/var/cache/prod_h<hash>/Container<id>/Shopware_Core_KernelProdContainer.php
RetryWebhookMessageFailedSubscriber::__construct(): Argument #3 ($failureStrategy)
must be of type string, Shopware\Core\Framework\Webhook\Service\RelatedWebhooks given
RetryWebhookMessageFailedSubscriber::__construct(): Argument #2 ($webhookOutboxStore)
must be of type Shopware\Core\Framework\Webhook\Outbox\WebhookOutboxStore,
Shopware\Core\Framework\Webhook\Service\RelatedWebhooks given

Alle vier haben dieselbe Ursache. Der Hinweis steckt im Pfad: Der Fehler wird nicht in vendor/shopware/core geworfen, sondern im kompilierten Container unter var/cache/.

Was dahintersteckt

RelatedWebhooks war ein Service für die Deduplizierung von Webhooks. Er kam mit Shopware 6.6.10.0 bzw. 6.7.0.0 in den Core und ist mit dem Pull Request #19145 („remove webhook deduplication and cross-app webhook health writes“) wieder verschwunden. Laut Git-Tags ist 6.7.14.0 die erste Version ohne die Klasse. Im selben Zug wurden die Konstruktoren von RetryWebhookMessageFailedSubscriber, WebhookHealthService und WebhookManager geändert.

Jetzt zum Worker. messenger:consume lädt beim Start einmal den kompilierten Symfony-Container und behält ihn im Speicher, bis der Prozess endet. Mit --time-limit=300 sind das bis zu fünf Minuten, mit --time-limit=590 fast zehn, und ein Worker ohne Limit läuft, bis ihn jemand beendet.

Ersetzt du in dieser Zeit den Code auf der Platte, hat der Worker den Container der alten Version im Speicher und lädt Klassen, die er noch nicht kennt, ab sofort aus den neuen Dateien. Der alte Container will RelatedWebhooks erzeugen, die Datei gibt es nicht mehr: Class not found. War die Klasse schon geladen, klappt das, dafür passt dann der frisch nachgeladene RetryWebhookMessageFailedSubscriber nicht mehr zu den Argumenten, die der alte Container übergibt. Daraus entstehen die beiden TypeErrors:

  • Argument #3 ($failureStrategy) ... RelatedWebhooks given: Der Worker lief mit dem Container von 6.7.12 oder 6.7.13 (vier Argumente inklusive Outbox-Store), auf der Platte liegt schon 6.7.14 oder neuer.
  • Argument #2 ($webhookOutboxStore) ... RelatedWebhooks given: Der Container stammt von 6.7.11 oder älter, also noch ohne Outbox-Store, der Code ist mindestens 6.7.12.

Die Ghost-Variante funktioniert genauso, nur über einen anderen Weg. WebhookManager ist im Core als lazy() registriert. Symfony erzeugt dafür eine Proxy-Klasse (WebhookManagerGhost…) und legt sie als proxy-classes.php neben den Container in dessen Cache-Verzeichnis, wo sie erst bei Bedarf nachgeladen wird. Shopware hängt einen Hash aus Version und aktiven Plugins an den Namen des Cache-Verzeichnisses (prod_h<hash>). Wird das alte Verzeichnis nach dem Update gelöscht, findet der alte Worker seine eigene Proxy-Klasse nicht mehr.

Ein Bug in Shopware ist das nicht. Dass es gerade den Webhook-Code trifft, liegt daran, dass RetryWebhookMessageFailedSubscriber auf das Worker-Event WorkerMessageFailedEvent hört und deshalb im laufenden Worker gebraucht wird. Mit jedem anderen Service, dessen Konstruktor sich zwischen zwei Versionen ändert, kann dir dasselbe passieren.

Prüfen, ob es wirklich das ist

Zwei Dinge sollten zusammenpassen.

Erstens die Version. Die installierte Version muss 6.7.14.0 oder neuer sein, bei der Argument #2-Variante 6.7.12.0 oder neuer:

composer show shopware/core | grep versions

Zweitens die Zeit. Die Fehler setzen kurz nach dem Update ein. Vergleich den Zeitstempel im Log mit dem Zeitpunkt deines Updates, und schau dir an, wie lange deine Worker schon laufen:

ps -eo pid,lstart,cmd | grep "messenger:consume" | grep -v grep

Ist ein Worker älter als das Update, hast du den Schuldigen. Liegt im Fehlerpfad ein prod_h<hash>-Verzeichnis, das unter var/cache/ nicht mehr existiert, ist das eine weitere Bestätigung.

Hören die Fehler nach ein paar Minuten von allein auf, hat der Prozessmanager (Supervisor, systemd oder ein Cronjob) den Worker nach dem Absturz oder nach Ablauf von --time-limit mit dem neuen Code neu gestartet. Dann ist nichts weiter kaputt. Nachrichten, die in dem Moment verarbeitet wurden, können aber fehlgeschlagen sein. Ein Blick auf den failed-Transport lohnt sich:

bin/console messenger:failed:show

Die Lösung

Akut reicht es, alle Worker neu zu starten. Mit Supervisor:

supervisorctl restart all

Mit systemd entsprechend systemctl restart auf deine Consumer-Units. Startet ein Cronjob die Worker, beende die alten Prozesse; der nächste Lauf holt sich den neuen Code.

Eine Falle gibt es hier, und die sieht man selten. bin/console messenger:stop-workers ist der übliche Weg, aus der Symfony-Dokumentation übernommen. Der Befehl schreibt aber nur einen Zeitstempel in einen Cache-Pool, und den prüfen die Worker regelmäßig. In Shopware liegt dieser Pool im Standard-Setup im versionsgebundenen Cache-Verzeichnis. Führst du den Befehl nach dem Update mit dem neuen Code aus, landet das Signal im neuen Verzeichnis, und der alte Worker liest weiter im alten. Shopware kennt das Problem selbst: Beim Aktivieren und Deaktivieren von Plugins ruft PluginLifecycleService eine Methode mit dem sprechenden Namen signalWorkerStopInOldCacheDir() auf. Für das Core-Update gibt es so etwas nicht. Starte die Worker deshalb über den Prozessmanager neu, oder führ messenger:stop-workers noch mit dem alten Code aus, bevor du ihn ersetzt.

Für das nächste Update sieht die Reihenfolge so aus:

# 1. Worker anhalten, solange noch die alte Version läuft
supervisorctl stop all
bin/console sales-channel:maintenance:enable --all

# 2. Neuen Code bereitstellen (composer update, Deployment, ...)

# 3. Update abschließen
bin/console system:update:prepare
bin/console system:update:finish
bin/console cache:clear

# 4. PHP-FPM neu laden, wenn OPcache keine Zeitstempel prüft
systemctl reload php8.3-fpm

# 5. Shop und Worker wieder starten
bin/console sales-channel:maintenance:disable --all
supervisorctl start all

Schritt 4 betrifft dich, wenn opcache.validate_timestamps=0 gesetzt ist. Shopware empfiehlt das in den Performance-Tweaks ausdrücklich, mit dem Hinweis, dass du OPcache dann bei jedem Deployment leeren musst, per FPM-Reload oder cachetool. Ohne den Reload liefert FPM im Web-Request alte Klassen aus dem Opcode-Cache, während neue Dateien frisch geladen werden. Das ist dieselbe Mischung wie im Worker, nur im Storefront statt in der Queue. Den Namen der FPM-Unit musst du an deinen Server anpassen; auf Shared Hosting geht das oft nur über das Kundenmenü des Hosters.

Wer mit dem Shopware Deployment Helper arbeitet, bekommt messenger:stop-workers im Upgrade-Ablauf bereits mitgeliefert. Wegen des Cache-Verzeichnisses würde ich mich nach einem Versionswechsel trotzdem nicht allein darauf verlassen und die Worker zusätzlich über den Prozessmanager neu starten.

Wenn das nicht hilft

Kommen die Fehler auch nach einem sauberen Neustart aller Worker wieder, läuft irgendwo noch ein Prozess, den dein Prozessmanager nicht kennt. Typische Kandidaten sind ein zweiter Server, der dieselbe Queue konsumiert, aber noch nicht aktualisiert ist, ein per nohup gestarteter Worker aus einer alten SSH-Session oder ein Container mit dem alten Image. Die ps-Ausgabe von oben auf allen Hosts zeigt das schnell.

Ist im Fehler gar kein messenger:consume beteiligt und tritt er im Web-Request auf, ist fast immer OPcache der Grund. Und wenn das Update selbst abgebrochen ist, etwa nach einem Timeout im Web-Updater, kann der Code auf der Platte ein Gemisch aus zwei Versionen sein. Dann hilft kein Neustart, sondern nur ein vollständiges composer install auf die Zielversion.

Webhook-Fehler in der Queue fallen selten jemandem auf, weil im Shop vorne nichts kaputtgeht. ShopSignal liest das Fehlerlog deines Shopware-Shops mit und zeigt dir neben den gruppierten Meldungen auch, wie viele Nachrichten in der Queue warten oder fehlgeschlagen sind. So siehst du am Morgen nach dem Update, ob ein alter Worker noch Ärger macht.