GraphQL validation error: locate the schema-query mismatch

The symptoms

• •The execution engine returns a response whose `errors[].extensions.code` is one of the validation classifications (commonly `GRAPHQL_VALIDATION_FAILED` or equivalent framework-specific code such as Apollo's `GRAPHQL_VALIDATION_ERROR`) while `data` is partially or wholly null.
• •The error message references a structural mismatch — an unknown field, an argument of the wrong type, a missing required argument, a non-null violation computed statically, or a fragment that does not apply — rather than a runtime throw from a resolver.
• •Repeating the same query directly against the schema via a non-application client (introspection tooling, sandbox, CLI) reproduces the same error, confirming the mismatch is between document and schema, not application state.
• •Logging or tracing shows the request never reaches resolvers for the offending selection set, or resolvers log no execution for the path cited in the error's `path` field.
• •Removing or rewriting the suspect field, fragment, variable, or directive causes the error to disappear without changes to resolver code, data, or downstream services.

Likely causes

• •A selected field name does not exist on the schema's object type for that parent, including case-sensitivity and the difference between an interface union member and an unrelated type.
• •An argument is missing (required arguments per the schema's argument definitions), has the wrong type, or is supplied with a variable whose declared type does not match the argument's schema type.
• •Directives are used incorrectly: a directive is repeated when not repeatable, applied to a wrong location, or supplied arguments that violate the directive's argument schema.
• •Fragments fail to apply: a fragment's type condition does not match the parent type, fragment cycles exist, or `__typename` conditions are inconsistent with inline fragments.
• •Input object values violate the schema: unknown fields, missing required fields, or values whose runtime coercion (list non-null rules, enum mapping) is rejected statically.
• •Variables, operation name, or document shape constraints imposed by the server (operation allow-listing, persisted-query registry, persisted-query manifest version mismatch) reject the document before algorithmic validation completes.

First ten minutes

1. 01Capture the full request: the GraphQL document string, the operation name, the variables map, and the HTTP status code recorded by your gateway or server. Do not retry yet.
2. 02Read the error's `message`, `locations` (line and column), `path`, and `extensions.code`. The `extensions.code` should explicitly classify the failure as validation rather than execution; if it does not, the failure mode here may not apply.
3. 03Open the deployed schema in effect at request time (SDL or introspection JSON) and locate the type and field named in `locations`. Compare field name, argument list, argument types, and directive applicability against the request document byte-for-byte at the cited line and column.
4. 04Cross-reference any client-side persisted-query, query allow-list, or schema-registry version identifier. A validation-classified error after a deploy frequently means the schema advanced and the document was not regenerated.
5. 05If using code-generated operations, confirm the generator input matches the deployed schema hash or version; a stale generated artifact is a common, evidence-anchored cause.
6. 06Record one verification query — the original document reduced to its minimum that still reproduces the error — before proposing any change.

Evidence to collect

• •The exact request document (string), operation name, and variables map as sent on the wire, with byte-for-byte fidelity to the failing call.
• •The error envelope: `errors[].message`, `errors[].locations`, `errors[].path`, and `errors[].extensions.code` and any framework-specific extensions such as `validationErrorRuleId`.
• •The schema in effect at request time: published SDL, introspection JSON, or registry-pinned schema hash/version, including any directive and scalar definitions that affect interpretation.
• •The persisted-query or operation allow-list state, including manifest version or SHA, for the requested operation name.
• •Server-side logs or traces scoped to the request ID, showing the validation phase classification and confirmation that resolvers for the affected path were not invoked.
• •The minimum reproducer: a reduced operation and variable set that still produces the same `extensions.code` and `message`, used as the regression check target.

Where to look

• •The boundary between the parsing stage and the algorithmic validation stage of a GraphQL server: validation runs after parsing and before execution, and its outputs are returned even when execution produces no `data`.
• •The type, field, argument, directive, fragment, and input-object definitions in the deployed schema artifact, including any server-applied directives that are not in the public SDL.
• •The schema-registry or persisted-query registry that pins operation hashes against schema versions; mismatches here surface as validation-classified rejections even when the document itself is structurally valid.
• •The client codegen pipeline output (operation documents and TypeScript/Flow/Swift/Kotlin types), since regeneration cadence is where schema-query drift enters the request.
• •The server's request middleware chain for any custom rule that may run before or instead of the standard validation rules, so a custom rule's identifier can be reported back as `extensions.validationErrorRuleId`.
• •The transport boundary (HTTP status code, content-type, response envelope) to confirm the server actually applied its own validation rather than a proxy returning a different error shape.

Diagnostic steps

1. 01From the captured error, take `errors[].locations[0]` (line, column) and inspect the document at that offset to identify the offending selection, argument, variable, or directive occurrence.
2. 02Resolve the parent type for the offending selection using the surrounding path (starting at the operation root type), then look up that field in the deployed schema. The schema is authoritative; "the client expected X" is not evidence.
3. 03For argument errors, compare argument names and declared types against the argument definitions on that field, including whether the argument is non-null, its scalar/enum/input-object type, and whether the supplied variable type matches.
4. 04For fragment errors, walk the fragment spread tree to confirm every fragment's type condition is compatible with the parent type at each spread site, and verify there are no fragment cycles.
5. 05For directive errors, confirm the directive is declared, applied at a supported directive location, not repeated unless declared repeatable, and that each directive argument matches the directive's argument schema.
6. 06For persisted-query allow-list rejections, compare the operation hash and schema version recorded at registration against those in effect now; a registry mismatch can be classified as a validation failure by the server.
7. 07Repeat each check by running the minimum reproducer against the deployed schema using a non-application client. If the reproducer passes there, the production failure is in the transport, middleware, or registry layer rather than the schema-document match.

Common mistakes

• •Assuming a network or resolver error when `extensions.code` and the absence of resolver execution point to validation; this leads to changes in resolvers or downstream services that cannot resolve the mismatch.
• •Comparing the request to a local or previously deployed schema instead of the schema in effect at request time; a registry-pinned schema is the only authoritative source for diagnosis.
• •Treating unknown-field errors as "the field was renamed" without checking case, aliases (the schema field is fixed, the document may alias), and interface vs. object type membership of the parent.
• •Ignoring the variable declarations on the operation: a variable type that does not match the argument's schema type is a validation error even when the literal value would coerce.
• •Mutating the schema or registered operations to silence the error without a reproducing test, which can mask the real cause and reappear under the next deploy.

Safe fixes

• •If `locations` points to an unknown field, replace the selection with one present on the parent type per the deployed schema, or add the field to the schema if the client requirement is authoritative; verify by re-running the captured operation.
• •If an argument is missing or mistyped, correct the document to match the field's argument definitions (names, types, nullability) and align variable declarations with the same argument types; verify by executing the minimum reproducer against the deployed schema.
• •If a directive is misused, remove or relocate it per the directive's declared locations, or correct its arguments to match the directive's argument schema; confirm no duplicate application unless the directive is repeatable.
• •If a fragment does not apply, change its type condition to a type that is implemented by the parent type at the spread site, or inline the selection at the correct site; check the fragment tree for cycles introduced by the change.
• •If the failure is a persisted-query or allow-list mismatch, re-register the operation against the current schema version (or update the manifest reference) so the registry's hash and schema version align; verify by sending the registered hash.
• •If client codegen produced the document, regenerate it from the schema hash/version in effect and redeploy the client artifact; verify by sending the regenerated document through the original transport.

Prove the fix

1. 01The minimum reproducer operation executes against the deployed schema (via the same transport and middleware chain) and returns `errors` with no `extensions.code` indicating validation, or an empty `errors` array when the operation is fully valid.
2. 02Server-side traces for the request ID show execution reaching resolvers for all non-skipped paths in the document; for fields that legitimately resolve to null, `data` contains those nulls and no validation code is reported.
3. 03A regression check re-runs the original failing document (un-reduced) end-to-end and observes the same `extensions.code` absence, with the request ID logged for audit; the check is repeated on each deploy that publishes a new schema hash.
4. 04If persisted-query flow is in use, the operation hash resolves in the registry against the current schema version, and the schema-version field in the response (where exposed) matches the deployed schema.
5. 05No custom validation rule identifier appears in `extensions` for the same input set, confirming either standard or expected-custom rule outcomes without silent rule changes.

Prevention and next steps

• •Pin schema checks to artifacts: generate clients from a registry-pinned schema hash/version and fail the build if generated artifacts drift from that pinned reference.
• •Treat the validation boundary as a release gate: run the operation suite against the candidate schema in CI before deploy so a validation-classified error is observable before traffic is exposed.
• •Version persisted-query registrations alongside schema versions and reject requests whose operation hash does not resolve against the current schema version.
• •Propagate `extensions.code` from the response into client telemetry unchanged so validation-classified failures can be distinguished from execution failures in dashboards and alerts.
• •Maintain an operation allow-list reviewed against schema change proposals; an allow-list entry whose target field, argument, or directive disappears in the next schema version is a known-warning review item.

Safe commands and checks

graphql-cli --schema <schema-sdl-or-introspection-json> validate --query <operations-file.graphql> --operationName <name> --variables '<json>' --report                                                                                                                               Run a read-only validation pass against a local copy of the deployed schema; useful for reproducing the validation error without contacting the server.
graphql-inspector diff <old-schema-sdl> <new-schema-sdl>                                                                                                                                Diff two schema artifacts to identify breaking changes; pair with CI to detect field removals, argument type changes, and directive removals before deploy.
apollo client:check --schema <schema-sdl> --query <operations-file.graphql>                                                                                                                    Read-only validation of an operation set against a schema; intended as a pre-commit or pre-deploy check that fails the run on any validation-classified error.
node -e "const fs=require('fs'); const doc=fs.readFileSync('<operations-file.graphql>','utf8'); console.log(JSON.stringify({lineBreaks:doc.split('\n').length},null,2))"        Print the line count of the operations file to map a reported `locations.line` to a visible region; no network access.