Debug Optimizely Graph queries with GraphiQL

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 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 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.

Cached template not working as expected

Symptoms
Stale data returned, cache does not update after content changes, performance does not improve with cached templates.

Resolution

Verify the cached template syntax:

query MyCachedQuery @cached(ttl: 300) {
  ArticlePage(limit: 10) {
    items {
      Name
      TeaserText
    }
  }
}

Cached templates have a time-to-live (TTL). Content updates do not reflect until the TTL expires.
Adjust TTL based on content update frequency: lower TTL for frequently updated content, higher TTL for stable content.
Review cache performance in the Graph Portal.

For implementation details, see Cached templates.