Debug invalid documents
Diagnosing malformed client queries
GraphQL · Function
syntaxError
A GraphQL syntax error is a request error raised when the server cannot parse the document, for example because of a missing bracket or invalid operation keyword. It is reported before execution, so the response has errors but no data.
How it works
A syntax error is a request error raised when the server cannot parse the GraphQL document, such as when a bracket is missing or an operation keyword is invalid. Parsing stops before execution, so the response contains errors without data; use the message and optional locations entries to identify the problem.
Returns
A GraphQL response containing an errors array; for a request syntax error, data is not included.
Key points
- Syntax errors are request-time failures caused by invalid client-supplied GraphQL text.
- An unmatched bracket is a representative parse failure.
- Using an unsupported root operation keyword can also make the document syntactically invalid.
- A syntax-error response does not include the data key.
- When provided, locations points to the relevant position in the submitted document.
- The server stops before resolver execution when parsing fails.
Common mistakes
- A syntax error prevents execution entirely, so do not expect partial data or resolver-side behavior.
- Read errors[].message for the human-readable diagnosis, rather than relying only on the HTTP status.
Example: Inspect a syntax error response
const response = await fetch("https://api.example.com/graphql", {
method: "POST",
headers: { "Content-Type": "application/json" },
body: JSON.stringify({
query: "query { viewer { id }"
})
});
const result = await response.json();
console.log(result.errors?.[0]?.message);The malformed query is rejected before field resolvers execute, so inspect the errors array and its message and locations fields.
When to use it
Handle request-error responses
Building GraphQL clients
Show line and column locations
Improving developer feedback
Interview questions
QWhat is a GraphQL syntax error?
A syntax error is a request error caused by a malformed GraphQL document, such as a missing bracket or invalid root operation keyword. The server reports it before execution, so the response omits data.
Follow-up: How would you locate the defect? Use the errors entry's message and its optional locations field, whose line and column identify the associated document position.
QHow is a syntax error represented in a response?
The response uses the top-level errors key to describe the failure. Unlike field errors, request errors occur before execution and therefore do not include data.
Follow-up: Can a response contain both data and errors? Yes, field errors may produce partial data, but syntax errors cannot because execution never starts.
QWhat commonly causes a GraphQL syntax error?
Typical causes include an unmatched bracket or an invalid operation-type keyword. A client or IDE linter can catch malformed query text before it is sent.
Follow-up: How does this differ from validation? A syntactically valid document can still fail schema validation when it refers to an invalid field or operation.
Related
Request errorsValidation errorField errorserrorsdatalocationsmessage