---
name: graphql-schema-debugger
description: "A fix for a GraphQL schema that refuses to load or misbehaves: each validation error or linter warning traced to its line, why the server rejects it, the corrected SDL snippet, and the resolver-side cause when the schema is fine but the data is wrong. Use when a GraphQL server rejects its schema, a linter reports errors, or a field returns null or triggers N+1 queries and the user has the SDL and the error output. Do not use for a general schema quality audit with no failing error, or designing a new schema. Related topics: coding, graphql."
---

# GraphQL Schema Debugger

A fix for a GraphQL schema that refuses to load or misbehaves: each validation error or linter warning traced to its line, why the server rejects it, the corrected SDL snippet, and the resolver-side cause when the schema is fine but the data is wrong.

## When to use

Use this skill when a GraphQL server rejects its schema, a linter reports errors, or a field returns null or triggers N+1 queries and the user has the SDL and the error output. Do not use it for a general schema quality audit with no failing error, or designing a new schema.

## Workflow

1. Ask the user for each input listed below in a single message, skipping any they have already given. Where options are listed, offer them, but accept other answers too.
2. Map each error message to the SDL line it refers to, distinguishing the use site from the definition that actually needs the change.
3. Explain for each issue what the spec or server rejects and give the corrected snippet for only that part of the schema.
4. Classify each issue as schema-side or resolver-side, and write the resolver fix in the selected language for null fields and N+1 patterns, batching against the named database.
5. Work through the specific concerns in the order given so the user's priority is addressed first.
6. List two or three practices that would catch these errors earlier in development.

## Inputs

- **Schema SDL** (longer free text)
- **Error output** (longer free text)
- **Database** (choose one: PostgreSQL, MongoDB, MySQL, Elasticsearch, Other)
- **Resolver language** (choose one: Node.js, Python, Java, Go, Other)
- **Specific concern** (choose any: Circular refs, N+1 queries, Type mismatches, Naming, Missing descriptions, Schema will not load, Field returns null unexpectedly)

## Output

A markdown report with a numbered issue list (line reference, why it fails, corrected snippet), a Resolver fixes section with code where relevant, and a short Prevention list.

## Prompt template

Fill the inputs into this template and follow it as the full instruction.

### GraphQL Schema Debugger

Find out why my GraphQL schema breaks and give me the corrected snippets.

#### Details
- Schema SDL: {{Schema SDL}}
- Error output: {{Error output}}
- Database: {{Database}}
- Resolver language: {{Resolver language}}
- Specific concern: {{Specific concern}}

Start from the error output and map each message to the line in the SDL it refers to, because schema validators report the symptom (unknown type, duplicate field, non-null cycle in input types) at the use site rather than the definition. For each issue state what the GraphQL spec or the server rejects, then give a corrected snippet of just that part of the schema. Separate schema errors from resolver errors: a type cycle or missing type is fixed in the SDL, while a field that returns null or an N+1 pattern is fixed in the resolver, so show the resolver fix in the selected language with a DataLoader or batched query against the named database where that is the cause. Treat the specific concerns as the priority order for the investigation. Close with two or three practices that would have caught these errors earlier, such as schema linting in CI or a composed-schema check.

## Pitfalls

- Editing the type where the error is reported when the real defect is in the type it references, which moves the error rather than fixing it.
- Adding a nullable marker to make a validation error disappear instead of resolving the input-type cycle behind it.
- Treating a null field as a schema bug when the resolver simply never returns the key the field expects.
