Jeder Block dieser Serie hatte sein eigenes kleines Troubleshooting-Kapitel oder zumindest einen warn()-Hinweis zum jeweils typischsten Fehler. Dieses Kapitel bündelt sie zu einem einzigen Nachschlagewerk, sortiert nach Symptom statt nach Ursache - so, wie ein Fehler im echten Betrieb zuerst auffällt.

Die allgemeine Diagnose-Reihenfolge

Bevor man ein einzelnes Symptom aus der Liste unten sucht, lohnt sich immer zuerst dieselbe generische Abfolge - für praktisch jedes der folgenden Probleme der schnellste erste Schritt:

bin/magento cache:flush
bin/log exception.log
bin/log mironsoft_loyalty.log
bin/magento deploy:mode:show
bin/magento setup:di:compile

Symptom-Tabelle

1. Punkte werden nach Bestellabschluss nicht gutgeschrieben. Wahrscheinlichste Ursache: Exception innerhalb von AwardPointsOnOrderPlaced wurde von dessen eigenem try/catch (\Throwable) abgefangen (Kapitel 30) und landet ausschließlich in var/log/mironsoft_loyalty.log (Kapitel 34), nicht in exception.log - der Checkout selbst läuft unauffällig weiter durch. Erster Schritt: bin/log mironsoft_loyalty.log statt exception.log.
2. Punkte werden doppelt gutgeschrieben, wenn ein Punkte-Paket gekauft wird. loyalty_points_multiplier (Kapitel 19) wurde auf dem Punkte-Paket-Produkt nicht auf 0 gesetzt - sowohl AwardPointsOnOrderPlaced (Kapitel 30) als auch CreditPurchasedPointsPackageOnOrderPlaced (Kapitel 76) buchen dann unabhängig voneinander Punkte für dieselbe Bestellung, siehe die dokumentierte Praxis-Empfehlung aus Kapitel 76.
3. Admin-Grid zeigt keine oder falsche Prämien. Entweder ein falsch aufgebauter EAV-Collection-Filter (addAttributeToFilter() statt der Kapitel-15-Helfer addActiveFilter()/addRewardTypeFilter()) oder ein neues Attribut, das nur dem Default-Set zugeordnet wurde, siehe die Warnung aus Kapitel 19/20.
4. PHPStan meldet einen Fehler direkt nach dem Anlegen eines neuen Configuration Type. setup:di:compile vergessen oder nur einmal statt zweimal ausgeführt - derselbe Fallstrick wie beim types-Array-Merge aus Kapitel 88/99 (feedback_di_xml_compile_gotcha).
5. Eine GraphQL-Query liefert unerwartet null nach einer Schema-Änderung. Der config-Cache wurde nach der Änderung an schema.graphqls nicht geleert - bin/cache-clean config reicht, kein setup:di:compile nötig (Kapitel 82/83, konsistent mit der GraphQL-Serie dieses Katalogs).
6. Ein Kunde bekommt beim Einlösen wiederholt HTTP 429. Kein Bug - RedemptionRateLimiter (Kapitel 86) hat MAX_ATTEMPTS = 5 innerhalb von WINDOW_SECONDS = 60 erreicht. Prüfen, ob der Client tatsächlich fehlerhaft wiederholt aufruft, nicht das Limit selbst anheben, ohne den Grund zu verstehen.
7. Die neue Zahlungsart erscheint nicht im Checkout. Entweder AvailabilityHandler::handle() (Kapitel 64) liefert false, weil quote.loyalty_points_to_redeem noch 0 oder null ist, oder die Knockout-Renderer-Registrierung in checkout_index_index.xml (Kapitel 65) fehlt nach einem Static-Content-Deploy ohne Admin-Bereich - siehe Kapitel 99, Schritt 6.
8. Die Gratisversand-Option erscheint nicht in der Versandartenliste. FreeShippingByPoints::collectRates() (Kapitel 66/67) liefert konsequent false statt eines leeren Result, sobald points_cost den aktuellen Punktestand übersteigt - das ist beabsichtigtes Verhalten, kein Fehler, siehe die Kapitel-67-Begründung.
9. company_form.xml zeigt loyalty_tier_override nicht an. AddLoyaltyTierOverridePlugin (Kapitel 22) prüft Magento_Companys Verfügbarkeit nicht selbst - fehlt das Modul im System, schlägt schon die extension_attributes.xml-Validierung fehl, siehe Kapitel 98.
10. setup:upgrade bricht mit einem Data-Patch-Fehler ab. Meist eine falsche oder zyklische getDependencies()-Deklaration - der vollständige, korrekte Abhängigkeitsgraph aller zwölf Patches steht in Kapitel 99.
11. Der ExpirePoints-Cronjob taucht als "missed" in cron_schedule auf. Entweder die Crongroup mironsoft_loyalty (Kapitel 32) ist nicht aktiv, oder die Reconciliation-Abfrage überschreitet schedule_lifetime mangels Index auf dem Ledger - siehe die Performance-Warnung aus Kapitel 100.

Das bekannte Restrisiko: Race Conditions

Wer diese Serie als Vorlage für ein echtes Modul nutzt, sollte nicht am selben Punkt aufhören, an dem dieses Tutorial aus didaktischen Gründen aufgehört hat - genau darum geht es in Kapitel 104, das weiterführende Serien dieses Katalogs zeigt.