How it works

The explanation, with examples you can run.

The shape of an error

1{2  "data": { "post": { "title": "Hello", "viewCount": null } },3  "errors": [4    {5      "message": "stats service timed out",6      "locations": [{ "line": 4, "column": 5 }],7      "path": ["post", "viewCount"],8      "extensions": { "code": "UPSTREAM_TIMEOUT" }9    }10  ]11}

path names the response position that failed, including list indexes (["posts", 3, "author"]). locations point into the query document. extensions is free-form; servers put machine-readable codes there. Keep messages in production generic and log the details server-side: stack traces and internal names in errors tell an attacker a lot.

How far a null travels

Your code

// How one failing field becomes null, and how far that null spreads.
// A field is [name, nonNull, children?]; resolving it may throw.
function execute(fields, source, path, errors) {
  const out = {}
  for (const [name, nonNull, children] of fields) {
    let value
    try {
      value = typeof source[name] === "function" ? source[name]() : source[name]
      if (children && value != null) value = execute(children, value, path.concat(name), errors)
    } catch (err) {
      if (err.propagate) value = null                     // a child already recorded the error
      else { errors.push({ message: err.message, path: path.concat(name) }); value = null }
    }
    if (value == null && nonNull) {                       // a non-null field can't hold null:
      const e = new Error("propagate"); e.propagate = true // hand the null to the parent
      throw e
    }
    out[name] = value
  }
  return out
}

function run(label, schema) {
  const errors = []
  let data
  try { data = execute(schema, root, [], errors) } catch { data = null }
  console.log(label, JSON.stringify(errors.length ? { data, errors } : { data }))
}

const root = {
  post: {
    title: "Hello",
    viewCount: () => { throw new Error("stats service timed out") },
  },
}

run("post: Post,  viewCount: Int   ->", [["post", false, [["title", true], ["viewCount", false]]]])
run("post: Post,  viewCount: Int!  ->", [["post", false, [["title", true], ["viewCount", true]]]])
run("post: Post!, viewCount: Int!  ->", [["post", true, [["title", true], ["viewCount", true]]]])

⌘/Ctrl + Enter

OutputNot run yet

Press Run to see what your code prints, in order.

Runs in this browser, in an isolated frame with no access to this page. console.log, info, warn and error are shown; code runs as a classic script, so use an async function for await.

The error is recorded once, at the field that failed; what changes is how much of the response is lost. With viewCount nullable, only that number is missing. Marking it Int! costs the whole post, and marking post non-null too costs the entire response. Put ! where a value is truly guaranteed, and leave fields that depend on other services nullable.

Errors as data

Errors in errors are for things that went wrong. Outcomes the user can act on, such as a duplicate email, a declined card or a missing permission they could request, are usually better modelled in the schema:

1type Mutation { signUp(input: SignUpInput!): SignUpResult! }2union SignUpResult = SignUpSuccess | EmailTaken | InvalidInput

The client then handles each case with typed fields instead of parsing messages, and the schema documents every outcome.

Check yourself

3 questions. Get them all right to finish this topic.

1.A response contains both `data` and `errors`. What does that mean?
2.`viewCount: Int!` on `Post` throws, and `post` is nullable. What is `data.post`?
3.What HTTP status does a GraphQL response with a resolver error usually have when served as `application/json`?

0 of 3 right so far. Get all three to finish this topic.

Errors: partial data and the errors array

How it works

The shape of an error

How far a null travels

Errors as data

Check yourself

Go deeper