GraphQL API Debugging Guide

Queries, variables, operation names, validation failures, partial data and HTTP behavior. Last updated August 31, 2026.

The GraphQL specification separates request errors from execution errors and describes how responses may contain data, errors and implementation-specific extensions. See the current GraphQL spec at spec.graphql.org. The GraphQL-over-HTTP draft also gives practical HTTP status recommendations for parse errors, validation failures, auth failures and server failures at graphql-over-http.

Minimal curl request

curl -i -X POST https://api.example.com/graphql \
  -H "Content-Type: application/json" \
  -H "Authorization: Bearer REPLACE_WITH_TEST_TOKEN" \
  --data '{"query":"query Viewer { viewer { id login } }"}'

Query with variables

{
  "operationName": "CustomerById",
  "query": "query CustomerById($id: ID!) { customer(id: $id) { id name email } }",
  "variables": {
    "id": "cus_123"
  }
}

Use the JSON Formatter before debugging variables. Many GraphQL failures start as ordinary JSON body mistakes: wrong variable shape, missing operationName, invalid string escaping or stale copied payloads.

Error classification

Symptom	Likely layer	Next check
Invalid JSON body	HTTP transport	Format the request body and inspect `Content-Type`.
GraphQL parse error	Query document	Check braces, field syntax and copied fragments.
Validation error	Schema contract	Check field names, argument names and variable types.
Auth error	Token or policy	Check bearer token, scopes, viewer identity and field-level authorization.
Partial data with errors	Resolver execution	Inspect error path, nullable fields and downstream service logs.

Debug checklist

endpoint:
operation name:
query hash:
variables valid JSON:
auth token scope:
http status:
data present:
errors present:
first error message:
error path:
resolver owner:
downstream service:

Production safeguards

Use operation names so logs and traces can group requests.
Capture variables separately from the query text, with sensitive values redacted.
Limit query depth or cost when public clients can submit arbitrary queries.
Watch for N+1 resolver behavior when one query fans out into many database calls.
Document which errors are request errors and which are partial execution errors.

GraphQL debugging starts by deciding whether the failure happened before execution or during execution. That one distinction prevents a lot of false backend hunts.