GraphQL error format - Step-by-Step Execution

Concept Flow - GraphQL error format

Client sends GraphQL query

↓

Server processes query

↓

Error occurs?

No→Return data response

Yes↓

Create error object

↓

Include error fields: message, locations, path, extensions

↓

Return error response to client

The server processes a GraphQL query and if an error occurs, it creates a structured error object with specific fields and returns it to the client.

Execution Sample

GraphQL

{
  user(id: "123") {
    name
    age
  }
}

// Error response example

A GraphQL query requesting user data, with an example error response returned if user not found.

Execution Table

Step	Action	Evaluation	Result
1	Receive query from client	Query with user(id: "123")	Start processing query
2	Resolve user field	Check if user with id 123 exists	User not found
3	Create error object	Build error with message and location	{"message": "User not found", "locations": [{"line": 2, "column": 3}], "path": ["user"]}
4	Return response	Include errors array in response	{"errors": [{"message": "User not found", "locations": [{"line": 2, "column": 3}], "path": ["user"]}], "data": {"user": null}}
5	End	Response sent to client	Execution complete

💡 Error detected during field resolution, error object created and returned in response

Variable Tracker

Variable	Start	After Step 2	After Step 3	Final
query	null	{ user(id: "123") { name age } }	{ user(id: "123") { name age } }	{ user(id: "123") { name age } }
userData	null	null (user not found)	null (user not found)	null (user not found)
errorObject	null	null	{"message": "User not found", "locations": [{"line": 2, "column": 3}], "path": ["user"]}	{"message": "User not found", "locations": [{"line": 2, "column": 3}], "path": ["user"]}
response	null	null	null	{"errors": [{"message": "User not found", "locations": [{"line": 2, "column": 3}], "path": ["user"]}], "data": {"user": null}}

Key Moments - 3 Insights

Why does the error response include both 'errors' and 'data' fields?

The 'errors' field contains details about what went wrong, while the 'data' field shows partial or null data. This allows clients to receive as much valid data as possible even if some parts failed, as seen in step 4 of the execution_table.

What is the purpose of the 'locations' field in the error object?

The 'locations' field shows where in the query the error happened (line and column). This helps developers quickly find and fix the problem, as shown in step 3 of the execution_table.

Why is the 'path' field included in the error object?

The 'path' field indicates which part of the query caused the error, helping clients understand which field failed. This is demonstrated in step 3 where the path is ["user"].

Visual Quiz - 3 Questions

Look at the execution_table, what is the value of 'userData' after step 2?

A Error object

B User object with id 123

C null (user not found)

D Query string

💡 Hint

Check the variable_tracker row for 'userData' after step 2

At which step is the error object created?

A Step 3

B Step 2

C Step 1

D Step 4

💡 Hint

Look at the execution_table action 'Create error object'

If the user was found successfully, how would the response differ at step 4?

A Errors array would contain error message

B Errors array would be empty and data would contain user info

C Data field would be null

D Response would be empty

💡 Hint

Consider the purpose of 'errors' and 'data' fields in the response

Concept Snapshot

GraphQL error format:
- Errors returned in 'errors' array
- Each error has 'message', 'locations', 'path'
- 'locations' shows query line/column
- 'path' shows field causing error
- 'data' may contain partial results
- Enables clients to handle errors gracefully

Full Transcript

When a GraphQL query is sent, the server processes it. If an error occurs, such as a missing user, the server creates an error object with a message, location in the query, and the path to the field that caused the error. This error object is included in an 'errors' array in the response. The 'data' field may still contain partial data or null for the failed field. This structured error format helps clients understand what went wrong and where, allowing better debugging and user experience.

Practice

1. What is the main purpose of the message field in a GraphQL error response?

easy

A. To describe what went wrong in the query

B. To show the exact line of code where the error occurred

C. To list all the fields requested in the query

D. To provide the user's authentication token

Solution

1. Step 1: Understand the role of the message field

   The message field clearly states the error description to help identify the problem.

2. Step 2: Compare with other fields

   Other fields like location show where the error happened, but message explains what the error is.

3. Final Answer:

   To describe what went wrong in the query -> Option A

4. Quick Check:

   message = error description [OK]

Hint: Message always explains the error clearly [OK]

Common Mistakes:

• Confusing message with location
• Thinking message holds query data
• Assuming message is optional

2. Which of the following is the correct structure of a GraphQL error object?

easy

A. { message: string, location: string, path: string }

B. { error: string, line: int, column: int, path: string }

C. { message: string, line: int, column: int, query: string }

D. { message: string, location: [{ line: int, column: int }], path: [string] }

Solution

1. Step 1: Recall GraphQL error object format

   GraphQL errors include message, location as an array of line and column objects, and path as an array of strings.

2. Step 2: Check each option's structure

   Only { message: string, location: [{ line: int, column: int }], path: [string] } matches the correct structure with proper types and nesting.

3. Final Answer:

   { message: string, location: [{ line: int, column: int }], path: [string] } -> Option D

4. Quick Check:

   Correct error object format = { message: string, location: [{ line: int, column: int }], path: [string] } [OK]

Hint: Look for location as array of line/column objects [OK]

Common Mistakes:

• Using location as a string
• Confusing path type with string instead of array
• Missing array brackets for location

3. Given this GraphQL error response snippet:

{"errors": [{"message": "Cannot query field 'age' on type 'User'", "locations": [{"line": 3, "column": 5}], "path": ["user", "age"]}]}

What does the path field indicate?

medium

A. The exact location in the query text where the error occurred

B. The sequence of fields leading to the error in the response data

C. The server file path where the error was logged

D. The user's file system path

Solution

1. Step 1: Understand the path field meaning

   The path shows the chain of fields in the response data that led to the error.

2. Step 2: Analyze the example path

   Here, the error is in the 'age' field inside the 'user' object, so path is ["user", "age"].

3. Final Answer:

   The sequence of fields leading to the error in the response data -> Option B

4. Quick Check:

   path = error location in response data [OK]

Hint: Path shows field chain causing error [OK]

Common Mistakes:

• Thinking path is query text location
• Confusing path with server file path
• Ignoring path as array of fields

4. You receive this GraphQL error response:

{"errors": [{"message": "Syntax Error: Expected Name, found }", "locations": [{"line": 5, "column": 10}]}]}

What is the most likely cause of this error?

medium

A. A missing or extra character in the query causing invalid syntax

B. A missing authentication token in the request headers

C. A server crash unrelated to the query

D. A network timeout error

Solution

1. Step 1: Interpret the error message

   The message says "Syntax Error: Expected Name, found }", indicating a syntax mistake in the query.

2. Step 2: Understand syntax errors in GraphQL

   Such errors happen when brackets, names, or punctuation are missing or misplaced in the query text.

3. Final Answer:

   A missing or extra character in the query causing invalid syntax -> Option A

4. Quick Check:

   Syntax error = query typo [OK]

Hint: Syntax errors mean query text is malformed [OK]

Common Mistakes:

• Assuming error is due to auth issues
• Confusing syntax error with server crash
• Ignoring location info in error

5. You want to add extra details to your GraphQL error responses for better debugging. Which field should you use to include custom error codes or metadata?

hard

A. locations

B. path

C. extensions

D. message

Solution

1. Step 1: Identify the field for extra error info

   The extensions field is designed to hold custom metadata like error codes or debugging info.

2. Step 2: Differentiate from other fields

   message is for error text, path shows error location in data, and locations shows query text position.

3. Final Answer:

   extensions -> Option C

4. Quick Check:

   extensions = custom error metadata [OK]

Hint: Use extensions for custom error details [OK]

Common Mistakes:

• Putting custom info in message
• Confusing path with metadata
• Ignoring extensions field existence