Über 24 Kapitel sind einige Stolperfallen bereits einzeln als Warnhinweise aufgetaucht. Dieses Kapitel bündelt sie zu einer systematischen Troubleshooting-Übersicht, sortiert nach Symptom statt nach Ursache - so lässt es sich als Nachschlagewerk nutzen, wenn tatsächlich etwas klemmt.

Symptom: jede GraphQL-Anfrage schlägt fehl, auch unabhängige

Fällt jede GraphQL-Anfrage aus - selbst für Core-Queries, die mit dem eigenen Modul nichts zu tun haben - liegt fast immer ein Syntax-/Parsing-Fehler in einer schema.graphqls vor (Kapitel 4). Das gesamte Schema wird als eine Einheit geparst; ein einzelnes kaputtes Modul reißt alle anderen mit.

• Fehlende oder überzählige geschweifte/eckige Klammer in einer der letzten Änderungen.
• Ein referenzierter Typ (z. B. SearchResultPageInfo, FilterTypeInput) existiert nicht, weil die Modulabhängigkeit in module.xml (Kapitel 4) fehlt oder falsch geschrieben ist.
• Ein Tippfehler im Typnamen bei extend type (Kapitel 8) - CategoryInterface statt Category ist der klassische Fall.

Symptom: "Cannot query field", obwohl der Code korrekt aussieht

Erst wenn ein frischer Cache-Clean das Problem nicht löst, lohnt sich der Blick auf tatsächliche Tippfehler im Feldnamen selbst - Groß-/Kleinschreibung zählt, GraphQL ist case-sensitive.

Symptom: ein Feld liefert immer null, obwohl Daten vorhanden sind

Drei mögliche Ursachen, in der Reihenfolge, wie sie sich am schnellsten ausschließen lassen:

1. Die @resolver-Direktive fehlt oder zeigt auf eine falsch geschriebene Klasse - der Default-Resolver aus Kapitel 2 greift dann und sucht einen gleichnamigen Array-Schlüssel, der beim komplexeren Feld gar nicht existiert.
2. Der übergeordnete Resolver liefert den erwarteten Schlüssel (z. B. model) im $value-Array nicht mit - eine Prüfung mit var_dump($value) oder xdebug (Kapitel 10) klärt das schnell.
3. Der Feld-Resolver selbst wirft eine stillschweigend abgefangene Exception - ein Blick in var/log/exception.log (bin/log exception.log) zeigt in diesem Fall den tatsächlichen Fehler.

Symptom: "Internal server error" ohne jedes Detail

Diese generische Meldung erscheint für jede Exception, die keine der vier GraphQL-Exceptions aus Kapitel 19 ist - im Produktivmodus wird die eigentliche Ursache bewusst maskiert. Für die lokale Entwicklung hilft der Wechsel in den Developer-Mode:

bin/magento deploy:mode:show
bin/magento deploy:mode:set developer
bin/log exception.log

Im Developer-Mode liefert die GraphQL-Antwort einen vollständigen Stacktrace im debugMessage-Feld der Fehlerantwort - im Produktivmodus bleibt dieses Feld leer, die vollständige Information findet sich dann nur im Server-Log.

Symptom: eine Mutation schlägt mit einem irreführenden Fehler fehl

Ein Klassiker bei Input-Typen (Kapitel 6, 16): Wird ein Pflichtfeld im input-Typ vergessen, meldet GraphQL bereits vor jedem Resolver-Aufruf einen Validierungsfehler direkt gegen das Schema - die Meldung nennt zwar das fehlende Feld, aber Einsteiger suchen den Fehler oft zuerst im PHP-Resolver, obwohl dieser in diesem Fall noch nie aufgerufen wurde.

Mit dieser Troubleshooting-Übersicht schließt sich der Kreis zurück zu Kapitel 1 - Kapitel 26 fasst als letztes Kapitel der Serie alle wichtigen Muster in einem kompakten Spickzettel zusammen.