GraphQL Queries in Magento mit Browser Devtools und Logs analysieren

1. Der Debugging-Workflow im Überblick

Bei Magento-Problemen, die mit GraphQL zusammenhängen, gibt es einen klaren Debugging-Workflow, der von der Browser-Oberfläche bis zum Resolver-Code führt. Der erste Schritt ist immer die Beobachtung im Browser: welche Requests werden ausgelöst, welche Status-Codes kommen zurück, welche Fehler erscheinen im Response-Body. Der zweite Schritt ist die Reproduktion der Query in einem dedizierten GraphQL-Client wie Altair, um den Browser-Kontext zu eliminieren und die Query isoliert zu untersuchen. Der dritte Schritt ist die Log-Analyse auf dem Server, um Resolver-Fehler zu finden, die in der Browser-Response nur als generische Fehlermeldung erscheinen. Der vierte Schritt ist gegebenenfalls Xdebug im Resolver-Code selbst.

Dieser Workflow gilt sowohl für Hyvä-Frontends als auch für klassische Magento-Luma-Themes, die GraphQL verwenden. In Hyvä werden GraphQL-Requests direkt aus Alpine.js-Komponenten abgesetzt – häufig per fetch im Template – was sie besonders einfach im Network-Tab zu finden macht, da sie als reguläre POST-Requests an /graphql erscheinen. Bei React- oder Vue-basierten Headless-Frontends ist das identisch: alle GraphQL-Requests landen an einem einzelnen Endpoint, was das Filtern im Network-Tab vereinfacht.

2. Chrome Network-Tab: GraphQL-Requests finden und inspizieren

Im Chrome DevTools Network-Tab lassen sich GraphQL-Requests am einfachsten über den Filter graphql in der Suchleiste finden – Chrome filtert dabei auf alle Requests, deren URL das Wort "graphql" enthält. Alternativ lässt sich nach Method: POST filtern, da GraphQL-Queries grundsätzlich als POST-Requests gesendet werden. In modernen Chrome-Versionen gibt es zudem einen dedizierten "Payload"-Tab, der JSON-formatierte Request-Bodies übersichtlich anzeigt – inklusive des query-Feldes, der operationName und der variables.

Besonders nützlich bei der Timing-Analyse im Network-Tab ist die Spalte "Waterfall": sie zeigt, wie viel Zeit ein GraphQL-Request in verschiedenen Phasen verbringt. Eine lange TTFB (Time to First Byte) deutet auf langsame Server-Verarbeitung hin – in der Regel langsame Resolver oder fehlende Caches. Eine kurze TTFB, aber lange Übertragungszeit, deutet auf einen zu großen Response-Payload hin. Diese Unterscheidung hilft, die Ursache klar einer der beiden Seiten zuzuordnen, bevor man in Logs oder Code wechselt.

# Im Chrome Network-Tab sichtbare Query-Payload
# Kopiert aus dem "Payload"-Tab eines /graphql POST-Requests

# Das "query"-Feld enthält die eigentliche GraphQL-Operation:
# {
#   "operationName": "GetCategoryProducts",
#   "variables": {
#     "categoryId": "15",
#     "pageSize": 12,
#     "currentPage": 1,
#     "sort": { "position": "ASC" }
#   },
#   "query": "..."
# }

query GetCategoryProducts(
  $categoryId: String!
  $pageSize: Int = 12
  $currentPage: Int = 1
  $sort: ProductAttributeSortInput
) {
  products(
    filter: { category_id: { eq: $categoryId } }
    pageSize: $pageSize
    currentPage: $currentPage
    sort: $sort
  ) {
    total_count
    page_info { current_page total_pages }
    items {
      __typename
      sku
      name
      url_key
      small_image { url label }
      price_range {
        minimum_price {
          final_price { value currency }
        }
      }
    }
  }
}

3. Query-Payload und Response analysieren

Die Response-Analyse im Network-Tab beginnt mit dem HTTP-Status. GraphQL gibt fast immer HTTP 200 zurück – selbst bei Fehlern. Nur bei vollständig ungültigen Requests (kein JSON, fehlender query-Parameter) erscheinen 400-Fehler. Im Response-Body zeigt sich die eigentliche Lage: ein errors-Array in der Response signalisiert GraphQL-Fehler, die parallel zu data existieren können. Ein leeres data-Feld bei einer Query, die Daten zurückgeben sollte, kombiniert mit einem gefüllten errors-Array, ist das häufigste Fehlerbild.

Für die detaillierte Response-Analyse empfiehlt sich die Chrome-Extension "JSON Viewer" oder das direkte Öffnen der Response in einem Tab. Bei großen Responses – Produktlisten mit vielen Feldern – ist die Übersicht im Browser schwer zu behalten. Hier hilft das Kopieren der gesamten Response in einen JSON-Beautifier oder direkt in Altair, wo die Response strukturiert angezeigt und mit dem Schema abgeglichen werden kann. Besonders hilfreich: das Feld extensions in der Magento-GraphQL-Response kann Tracing-Informationen enthalten, wenn developerMode aktiv ist oder das Tracing-Plugin aktiviert wurde.

4. Magento-spezifische Headers verstehen

Magento-GraphQL-Requests haben mehrere spezifische Request-Header, die das Verhalten der API beeinflussen und beim Debugging relevant sind. Der Store-Header gibt den Store-Code an (Store: de) und bestimmt, welcher Magento-Store mit welcher Sprache, Währung und Konfiguration antwortet. Fehlt dieser Header oder ist er falsch, antwortet Magento mit dem Default-Store – was zu Preisen in falscher Währung, fehlenden Übersetzungen oder nicht existierenden Produkten in der Antwort führen kann.

Der Authorization-Header enthält den Bearer-Token für authentifizierte Requests. In Hyvä-Frontends wird der Token nach dem Login im LocalStorage gespeichert und bei jedem GraphQL-Request im Header mitgesendet. Im Network-Tab ist er im "Headers"-Abschnitt des jeweiligen Requests sichtbar. Ein fehlender oder abgelaufener Token bei einem Kundenkontext-Query ist die häufigste Ursache für unerwartete Autorisierungsfehler. Der Content-Currency-Header ermöglicht store-übergreifende Währungsumrechnung und spielt bei Multi-Currency-Setups eine wichtige Rolle beim Debugging falscher Preisanzeigen.

# Magento-spezifische GraphQL-Headers im Request
# Sichtbar im Chrome DevTools > Network Tab > Headers

# Request Headers (Beispiel):
# POST /graphql HTTP/1.1
# Content-Type: application/json
# Store: de
# Authorization: Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...
# Content-Currency: EUR
# X-Magento-Cache-Id: abc123def456  (für Varnish/CDN-Caching)

# Häufige Fehlerursachen durch falsche Headers:
# - "Store: default" statt "Store: de" -> falsche Sprache und Preise
# - Kein Authorization-Header bei customer.orders Query -> 401/leere Response
# - Abgelaufener Bearer-Token -> extensions.category: "graphql-authorization"

# Response Header zum Caching prüfen:
# X-Cache: HIT   -> Varnish/Fastly hat gecacht
# X-Cache: MISS  -> Query ging durch zu Magento
# Cache-Control: max-age=0, must-revalidate -> nicht gecacht (dynamische Daten)

query CustomerContext {
  customer {
    firstname
    lastname
    email
    orders(pageSize: 5) {
      items {
        number
        status
        order_date
        total { grand_total { value currency } }
      }
    }
  }
}

5. Altair: Query aus dem Browser reproduzieren

Altair GraphQL Client ist das bevorzugte Tool, um Magento-GraphQL-Queries aus dem Browser-Kontext zu reproduzieren und isoliert zu debuggen. Der Workflow ist einfach: Query und Variables aus dem Chrome Network-Tab kopieren, in Altair einfügen, den Authorization-Header und den Store-Header konfigurieren und den Request absetzen. Altair zeigt die Response strukturiert an, validiert die Query gegen das Schema (sofern Introspection aktiv ist) und erlaubt, Variables bequem zu ändern, um unterschiedliche Szenarien zu testen.

Ein wichtiger Schritt beim Übertragen vom Browser in Altair: den vollständigen Request-Header-Satz kopieren, nicht nur den Authorization-Token. Store-Header, Currency-Header und ggf. Custom-Header für A/B-Testing oder Feature-Flags müssen alle mitgenommen werden, damit Altair exakt dasselbe sieht wie das Frontend. Für Magento-Entwickler, die regelmäßig debuggen, empfiehlt sich das Speichern von Altair-Environments pro Store-View mit allen benötigten Headers – das spart bei jedem Debugging-Session den manuellen Header-Setup.

6. Magento-Logs: system.log und exception.log auswerten

Wenn eine GraphQL-Response einen Fehler enthält, dessen Nachricht generisch ist ("Internal server error"), liegt die eigentliche Fehlerursache im Magento-Log. Magento reduziert Fehler in Produktionskonfigurationen bewusst zu generischen Meldungen, um keine internen Details zu exponieren. Das exception.log enthält den vollständigen Stack-Trace der Exception, inklusive Dateiname, Zeilennummer und aufgerufene Methoden. Das system.log enthält Meldungen aus dem Magento-Logging-System, die Resolver per $this->logger->critical() oder $this->logger->error() schreiben.

Im Mark-Shust-Docker-Setup wird das Log mit bin/log exception.log verfolgt. Im Entwicklungsmodus gibt Magento den vollständigen Fehlertext direkt in der GraphQL-Response im errors[].message-Feld zurück – was das Debugging stark vereinfacht. In Produktion muss man auf den Log-Vergleich setzen: Zeitstempel der fehlerhaften Request aus dem Browser-Network-Tab notieren und im Log nach demselben Zeitstempel suchen. Zusätzlich hilft das Aktivieren von Magentos developerMode temporär auf der Staging-Umgebung, um vollständige Fehlermeldungen in der GraphQL-Response zu erhalten.

# Fehleranalyse: Diese Response-Struktur tritt bei Resolver-Exceptions auf.
# In Produktion: "Internal server error" ohne Details
# In DeveloperMode: vollständiger Fehlertext im "message"-Feld

# Beispiel-Response bei einem Resolver-Fehler (DeveloperMode):
# {
#   "errors": [
#     {
#       "message": "No such entity with id = 99999",
#       "category": "graphql-no-such-entity",
#       "locations": [{ "line": 3, "column": 5 }],
#       "path": ["product"]
#     }
#   ],
#   "data": { "product": null }
# }

# Entsprechende Log-Einträge in var/log/exception.log:
# [2026-05-09 12:34:56] main.CRITICAL: No such entity with id = 99999
# Magento\Catalog\Model\ResourceModel\Product::load()
# ... (Stack-Trace)

# Suche im Log nach: bin/log exception.log | grep "2026-05-09 12:34"

query GetProductById($id: Int!) {
  product(id: $id) {
    sku
    name
    price_range {
      minimum_price { final_price { value currency } }
    }
  }
}

7. Xdebug in Resolver-Methoden einsetzen

Xdebug im Magento-Resolver erlaubt die tiefste Debugging-Ebene: Schritt-für-Schritt-Ausführung des Resolver-Codes mit vollem Zugriff auf alle Variablen und den Stack. Im Mark-Shust-Docker-Setup wird Xdebug mit bin/xdebug enable aktiviert. Danach einen Breakpoint in der Resolver-Klasse – typischerweise in der resolve()-Methode – setzen und den GraphQL-Request im Browser oder in Altair erneut auslösen. PhpStorm empfängt die Debug-Verbindung und hält die Ausführung am Breakpoint an.

Ein häufiges Problem beim Xdebug-Einsatz mit GraphQL: die Response-Timeout-Einstellung des Browsers. GraphQL-Requests, die durch den Debugger pausiert werden, überschreiten schnell das Browser-Timeout von 30–60 Sekunden. Altair ist hier besser geeignet als der Browser, weil es keinen automatischen Timeout hat. Alternativ lässt sich mit bin/debug-cli enable Xdebug für CLI-Commands aktivieren, was für GraphQL-Integrationstests in PHPUnit nützlich ist. In tiefen Resolver-Ketten empfiehlt sich außerdem das Setzen von xdebug.max_nesting_level auf einen höheren Wert, da Magento-Resolver häufig tiefe Aufruf-Hierarchien haben.

8. Debugging-Werkzeuge im Vergleich

Unterschiedliche Debugging-Szenarien erfordern unterschiedliche Werkzeuge. Die Wahl hängt davon ab, ob der Fehler im Browser-Frontend, im Netzwerk-Protokoll, im Magento-Resolver oder in der Datenzugriffsschicht liegt.

In der Praxis beginnt jede Debugging-Session mit dem Chrome Network-Tab, um den fehlerhaften Request zu identifizieren und den Payload zu kopieren. Der zweite Schritt ist die Reproduktion in Altair. Wenn dort ein Fehler auftritt, folgt der Blick ins exception.log. Für schwer reproduzierbare Fehler oder komplexe Resolver-Logik ist Xdebug der letzte Schritt. Das MySQL-Query-Log hilft zusätzlich, wenn der Resolver korrekt antwortet, aber trotzdem langsam ist.

9. Zusammenfassung

Das Analysieren von GraphQL-Queries in Magento ist ein mehrstufiger Prozess vom Browser bis zum Resolver-Code. Chrome DevTools Network-Tab liefert den vollständigen Request-Payload inklusive Operation-Name, Variables und Headers. Magento-spezifische Headers wie Store und Authorization sind entscheidend für korrekte API-Responses. Altair ermöglicht die isolierte Reproduktion ohne Browser-Kontext mit voller Schema-Exploration. Magento-Logs liefern bei generischen Fehlern den vollständigen Stack-Trace. Xdebug ermöglicht Schritt-für-Schritt-Debugging im Resolver-Code selbst.

Der wichtigste Grundsatz: immer mit dem Browser beginnen, den Request verstehen und erst dann in die tieferen Schichten wechseln. Viele Magento-GraphQL-Probleme – falsche Store-Header, abgelaufene Tokens, fehlende Variables – sind bereits auf Browser-Ebene diagnostizierbar, ohne eine einzige Log-Datei öffnen zu müssen.

11. FAQ: GraphQL Queries in Magento mit DevTools und Logs analysieren