---
title: Debug GraphQL queries
slug: graph/docs/debug-graphql-queries
createdAt: 2026-07-30T20:30:19.179Z
---

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](docId\:EAmxUkGUzFACSXzC4A0Xs).

## 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**

1. Start with a minimal query and build incrementally:

```graphql
# 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
    }
  }
}
```

2. Use query variables for testing dynamic values:

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

```json
{
  "name": "My Article"
}
```

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

```json
{
  "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.

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

```graphql
# 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.

```graphql
# 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](docId\:EAmxUkGUzFACSXzC4A0Xs).

**Field does not exist**

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

**Resolution**

1. Open [GraphiQL IDE](https://cg.optimizely.com/app/graphiql) and use autocomplete (`Ctrl+Space`) to verify available fields.
2. Check field name spelling and casing. GraphQL is case-sensitive.
3. Run an introspection query to confirm the field exists:

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

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

For schema details, see the [GraphQL schema documentation](docId\:sNcLLcLYgWv_QVb0Mtqus).

**Query timeout**

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

**Resolution**

1. Reduce query complexity: limit nested relationships, select only needed fields, and add pagination.
2. Compare an optimized query against the problematic one:

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

3. Use [cached templates](docId:736F1ShKUnQigeW1cwXMH) for repeated query structures.
4. Implement pagination for large result sets.

For optimization patterns, see [GraphQL best practices](docId\:nMQl7IokGuc0Wlq_dWwIG).

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

1. Verify the field is marked as filterable in the content type configuration.
2. Confirm the correct filter operator:

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

3. Test complex filters in GraphiQL before implementing them in code.

For the full list of operators, see [Filter content with Optimizely Graph](docId\:sNcLLcLYgWv_QVb0Mtqus).

**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:

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

```json
{ "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**

1. Declare all variables in the query definition:

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

2. Check for missing closing brackets (`}` or `)`), mismatched quotes, and incorrect field names.
3. Validate the query in [GraphiQL IDE](https://cg.optimizely.com/app/graphiql) before deploying.

**Query complexity limit exceeded**

**Symptoms**
`Query complexity of 1500 exceeds maximum of 1000` error.

**Resolution**

1. Request only the fields you need.
2. Remove deeply nested relationships (keep depth to five levels or fewer).
3. Add pagination with `limit` to reduce result set size.
4. Break one complex query into multiple focused queries.

For optimization techniques, see [GraphQL best practices](docId\:nMQl7IokGuc0Wlq_dWwIG).

## Performance issues

Optimize query performance and resolve caching problems. For detailed optimization strategies, see [GraphQL best practices](docId\:nMQl7IokGuc0Wlq_dWwIG) and [Cached templates](docId:736F1ShKUnQigeW1cwXMH).

**Slow query performance**

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

**Resolution**

1. Limit query depth to five levels or fewer.
2. Select only the fields you need.
3. Use pagination (`limit` and `skip`, or cursor-based) for large result sets.
4. Use [cached templates](docId:736F1ShKUnQigeW1cwXMH) for repeated query structures.
5. Use `item` instead of `items` when fetching a single result. See [Item queries for single entities](docId\:gC8t2E0x4Tg5TWjsAc6hL).
6. Measure execution time to identify the slowest queries and optimize those first.