Skip to content
Tutorials Center
My learning

Topics

Lesson 15 of 37 ยท Resolvers and Execution

How Execution Works and How Errors Behave

Follow a GraphQL request through parse, validate and execute, and learn how field errors, the errors array, null bubbling and serial mutations behave.

When a GraphQL request arrives, the server does not simply run your resolvers. It first checks that the text is a legal query, then that the query makes sense for your schema, and only then does it start calling code. Understanding these three phases explains almost every error message you will ever see, and it explains the odd-looking responses that carry both data and errors.

Reminder: no real GraphQL server runs on this site. The runnable examples use a hand-written stand-in executor that follows the same rules as a real one, in a much smaller form. Real libraries add many more checks and features.

If you have not yet seen how a single resolver is called, read Resolvers first.

Three phases: parse, validate, execute

Every request, three phases

Parse Turn the text into a tree. Syntax errors stop here.
Validate Check the tree against the schema.
Execute Run resolvers field by field.

Resolvers only run if the first two phases pass.

1 / 2

Parse. The server turns the query string into a tree (an abstract syntax tree). A missing brace or a stray character fails here. The response has an errors list and no data key, because nothing was executed.

Validate. The server walks that tree against your schema and applies a list of rules defined by the specification. Does every field exist on its type? Do object fields have a selection set and leaf fields none? Are all variables defined and used? Do arguments have the right types? Validation never touches your data or your resolvers, which is why it is cheap and why a bad query can be rejected before it costs anything. A validation failure also returns errors without data.

Execute. Only now does the server call resolvers, starting at the root fields and moving down. Problems that happen here depend on the data and the code (a database is down, a record is missing), so they are field errors. A response can then contain a mix of good data and errors.

flowchart LR
    A["Query text"] --> B["Parse"]
    B -->|"syntax error"| X["errors only"]
    B --> C["Validate"]
    C -->|"invalid"| X
    C --> D["Execute"]
    D --> E["data and maybe errors"]

A request fails early with errors only, or reaches execution and returns data.

The shape of an error

Each entry of the errors array is an object. Only message is required, but a good entry has more:

JSON
{
  "message": "Not allowed",
  "locations": [{ "line": 1, "column": 9 }],
  "path": ["secret"],
  "extensions": { "code": "FORBIDDEN" }
}
  • message is a human-readable text. Treat it as something that may be shown in logs, not as something clients should parse.
  • locations points into the query text. Validation and syntax errors always have it.
  • path lists the response keys (and list indexes) leading to the field that failed, for example ["posts", 1, "author"]. Execution errors have it, which lets a client match an error to the exact place in data.
  • extensions is a free-form object reserved for extra data. The convention is to put a machine-readable code there, such as FORBIDDEN or NOT_FOUND, because clients should branch on codes rather than on message text.

Field errors and partial data

If a resolver throws, the server records an error with that field's path and sets the field to null. All the sibling fields still run. That is the big difference from a REST call, where a failing handler usually means the whole response fails.

JSON
{
  "data": { "hello": "world", "secret": null },
  "errors": [
    {
      "message": "Not allowed",
      "path": ["secret"],
      "extensions": { "code": "FORBIDDEN" }
    }
  ]
}

A client must therefore look at both keys, and an HTTP status of 200 does not mean everything worked.

Null bubbling

A field can only become null if its type allows it. If a field marked non-null (!) fails or returns null, the server cannot put null there, so the null moves up to the nearest nullable parent. If that parent is itself non-null, it moves up again. If it reaches the top, the whole data becomes null. This rule is explained from the schema side in Lists and Non-Null Types.

The stand-in below makes all of this visible. It has a parse step, a validate step and an execute step, a resolver that throws, and a post whose author is missing. Run it and compare the five responses with the rules above.

Node.js Phases and errors in a stand-in executor

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

What happened:

  1. { hello secret }: the secret resolver threw, so secret is null, hello is still there, and the error carries the code from extensions.
  2. { hello colour }: validation failed (colour is not a field), so no resolver ran and there is no data key at all.
  3. posts is [Post], so each item may be null. The second post's author is declared non-null but resolved to null; that bubbles up one level and the item becomes null. The first post is untouched.
  4. strictPosts is [Post!]!, so items may not be null. The bubble climbs from the item to the list, and from the list (also non-null) to data, which becomes null. A single missing author wiped out the entire response.
  5. { hello never got past parsing.

Case 4 is the practical lesson: the more ! you put in a schema, the larger the blast radius of one failure.

Parallel queries, serial mutations

Fields in a selection set are independent, so the executor is allowed to resolve them in parallel. Slow fields therefore overlap, and the total time is roughly that of the slowest one. The specification makes one exception: the root fields of a mutation must run one after another, in the order written, because later changes may depend on earlier ones. (Subfields inside a mutation's result run normally.)

The stand-in below logs when each field starts and finishes. A short delay stands in for a database call.

Node.js Parallel fields versus serial mutation fields

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with node:readline or process.stdin), it gets the next line from this box.

In the parallel run every start line comes first and the end lines arrive in order of duration, yet the result keeps the order of the query. In the serial run each field finishes before the next starts. This is why two mutation fields in one request are safe to depend on each other, and why you should not hide slow work inside them.

A real server may also catch errors thrown by your code and hide the details of unexpected ones. Most libraries show the message of an error you created for clients, but replace unknown exceptions (a database driver error with SQL in it) with something generic such as "Internal server error". Check what yours does before you rely on error text.

Check your understanding

Quick check ยท 5 questions

of 5 answered You scored / 5 ยท perfect!

  1. 1. A query asks for a field that does not exist on a type. What does the response look like?

    This is a validation error. Validation happens before execution, so nothing is resolved and there is no data.
  2. 2. Which key in an error entry is the conventional place for a machine-readable code like FORBIDDEN?

    The extensions object is free-form and meant for extra information. Clients should branch on a code there rather than on message text.
  3. 3. A resolver for a nullable field throws. What happens to the sibling fields?

    Only the failing field becomes null, with an error recorded at its path. Siblings are independent.
  4. 4. In [Post!]! one post fails to produce a required non-null field. What can the final data be?

    Items and the list are non-null, so the null keeps moving up. With no nullable ancestor, the entire data is null.
  5. 5. How are the root fields of a mutation executed?

    The specification requires mutation root fields to run one after another so later changes can rely on earlier ones.

Summary

  • A request goes through parse, validate and execute; the first two produce errors only.
  • Execution errors are field errors: the field becomes null, siblings continue, and errors records its path.
  • Put a machine-readable code in extensions; never make clients parse message.
  • A failing non-null field bubbles its null to the nearest nullable parent, possibly all of data.
  • Query fields may resolve in parallel; mutation root fields run serially.
  • Always check errors even when the HTTP status is 200.

Next: The N+1 Problem and DataLoader.