Debug GraphQL queries

11 min

Isolate and fix query issues faster with GraphiQL, structured error analysis, and systematic simplification techniques. For the full error taxonomy and HTTP status code reference, see Error handling and rate limits.

Use GraphiQL for query development

GraphiQL is an interactive GraphQL IDE for building, testing, and debugging queries against your Optimizely Graph instance.

Access GraphiQL: https://cg.optimizely.com/app/graphiql?auth=YOUR_SINGLE_KEY

GraphiQL provides autocomplete (Ctrl+Space), real-time error highlighting, a Documentation Explorer for browsing the schema, query execution, and query history.

Debugging workflow

Start with a minimal query and build incrementally:

# Start minimal
query Test {
  ArticlePage {
    total
  }
}

# Add fields one at a time
query Test {
  ArticlePage {
    total
    items {
      Name
    }
  }
}

# Add filters last
query Test {
  ArticlePage(where: { Name: { eq: "Test" } }) {
    total
    items {
      Name
    }
  }
}

Use query variables for testing dynamic values:

query TestWithVariables($name: String) {
  ArticlePage(where: { Name: { eq: $name } }) {
    items {
      Name
    }
  }
}

{
  "name": "My Article"
}

Check the response for both the errors array and partial data results.

Analyze error messages

GraphQL returns errors in a structured JSON format. Understanding the structure helps you locate the exact problem.

Error response structure

{
  "errors": [
    {
      "message": "Human-readable error description",
      "locations": [{ "line": 4, "column": 7 }],
      "path": ["ContentType", "items", 0, "FieldName"],
      "extensions": {
        "code": "ERROR_CODE"
      }
    }
  ],
  "data": null
}

Key fields

message – What went wrong

locations – The line and column in your query where the error occurred

path – Which field in the result caused the error

extensions.code – Error category (for example, GRAPHQL_VALIDATION_FAILED or UNAUTHENTICATED)

Common error codes

Code	Meaning	Action
GRAPHQL_VALIDATION_FAILED	Invalid query structure	Check field names and types
GRAPHQL_PARSE_FAILED	Syntax error	Fix missing brackets or quotes
UNAUTHENTICATED	Authentication missing or invalid	Verify credentials
FORBIDDEN	Insufficient permissions	Check access rights and tokens
INTERNAL_SERVER_ERROR	Server-side issue	Contact support with query details

Simplify complex queries

When a complex query fails, simplify it to isolate the problem. Three approaches work well.

Binary search – Comment out half of your query, test, then narrow down which section causes the error.

query Debug {
  ArticlePage {
    items {
      Name
      # TeaserText
      # MainBody {
      #   html
      # }
      # Category {
      #   Name
      # }
    }
  }
}

Build incrementally – with the smallest valid query and add one field at a time until the error appears.

# Step 1
{ ArticlePage { total } }

# Step 2
{ ArticlePage { total items { Name } } }

# Step 3
{ ArticlePage { total items { Name TeaserText } } }

Test filters separately – Remove all filters first, then add them back one at a time to find the problematic filter.

# Without filters
query Test {
  ArticlePage {
    items { Name }
  }
}

# Add one filter
query Test {
  ArticlePage(where: { Name: { eq: "Test" } }) {
    items { Name }
  }
}

GraphQL query errors

Resolve query validation failures, timeouts, and filter errors. For the full error taxonomy, see Error handling and rate limits.

Field does not exist

Symptoms Cannot query field 'FIELD_NAME' on type 'CONTENT_TYPE' error, HTTP 400 Bad Request, query validation fails.

Resolution

Open GraphiQL IDE and use autocomplete (Ctrl+Space) to verify available fields.

Check field name spelling and casing. GraphQL is case-sensitive.

Run an introspection query to confirm the field exists:

query CheckFields {
  __type(name: "ArticlePage") {
    fields {
      name
      type {
        name
        kind
      }
    }
  }
}

Ensure the content type has been synchronized to Graph after any schema changes.

For schema details, see the GraphQL schema documentationGraphQL schema documentation.

Query timeout

Symptoms HTTP 504 Gateway Timeout, Query execution timeout error, slow query performance.

Resolution

Reduce query complexity: limit nested relationships, select only needed fields, and add pagination.

Compare an optimized query against the problematic one:

# Optimized: flat structure with pagination
query FastQuery {
  ArticlePage(limit: 20) {
    items {
      Name
      Category {
        Name
      }
    }
  }
}

Use cached templates for repeated query structures.

Implement pagination for large result sets.

For optimization patterns, see GraphQL best practices.

Invalid filter or where clause

Symptoms Field is not filterable or Invalid filter operator error, HTTP 400 Bad Request, filter does not work as expected.

Resolution

Verify the field is marked as filterable in the content type configuration.

Confirm the correct filter operator:

where: {
  Name: { eq: "Exact Match" }
  StartPublish: { gte: "2024-01-01" }
  Tags: { in: ["tag1", "tag2"] }
  Description: { contains: "keyword" }
}

Test complex filters in GraphiQL before implementing them in code.

For the full list of operators, see Filter content with Optimizely GraphFilter content with Optimizely Graph.

Variable type mismatch

Symptoms Expected type "String", found 123 or Expected type "Int", found "abc" errors.

Resolution Ensure the variable value matches the declared type in the query definition:

# Declare the type to match the variable value
query GetArticle($id: Int!) {
  ArticlePage(where: { Id: { eq: $id } }) {
    items { Name }
  }
}

{ "id": 123 }

Common mismatches: passing a number where a String is expected, or a quoted number where an Int is required.

Query syntax errors

Symptoms Syntax Error GraphQL request: Expected Name, found $ error, HTTP 400 Bad Request.

Resolution

Declare all variables in the query definition:

# Declare $name before using it
query GetArticles($name: String!) {
  ArticlePage(where: { Name: { eq: $name } }) {
    items { Name }
  }
}

Check for missing closing brackets (} or )), mismatched quotes, and incorrect field names.

Validate the query in GraphiQL IDE before deploying.

Query complexity limit exceeded

Symptoms Query complexity of 1500 exceeds maximum of 1000 error.

Resolution

Request only the fields you need.

Remove deeply nested relationships (keep depth to five levels or fewer).

Add pagination with limit to reduce result set size.

Break one complex query into multiple focused queries.

For optimization techniques, see GraphQL best practices.

Performance issues

Optimize query performance and resolve caching problems. For detailed optimization strategies, see GraphQL best practices and Cached templates.

Slow query performance

Symptoms Queries take longer than expected, inconsistent response times, timeout errors on complex queries.

Resolution

Limit query depth to five levels or fewer.

Select only the fields you need.

Use pagination (limit and skip, or cursor-based) for large result sets.

Use cached templates for repeated query structures.

Use item instead of items when fetching a single result. See Item queries for single entities.

Measure execution time to identify the slowest queries and optimize those first.