Skip to content

Errors

Responses follow the GraphQL specification. A request that cannot be executed at all, such as one with a syntax error, a missing non-null variable, an unknown operation name or a complexity or depth over the limit, is answered with errors and no data:

{"errors":[{"message":"missing required variable n"}]}

Field errors

When a resolver raises, the message that handle_exception on the context returns is added to errors with the field's path and its locations in the query, and the field becomes null:

{
  err
}

{
  "data": {"err": null},
  "errors": [
    {"message": "handled", "locations": [{"line": 2, "column": 3}], "path": ["err"]}
  ]
}

Elements of a list carry their index in the path, for example ["items", 0, "boom"].

Null propagation

A field declared with a nilable return type simply becomes null. A failed field with a non-null type cannot, so the failure moves up to the nearest ancestor that can be null, all the way to "data": null when nothing in between is nullable. Given leaf returning a nullable object and required a non-null string:

{ ok leaf { ok required } }

{
  "data": {"ok": "ok", "leaf": null},
  "errors": [{"message": "required failed", "locations": [{"line": 1, "column": 16}], "path": ["leaf", "required"]}]
}

Lists behave the same way per element: a failed nullable element is null, a failed non-null element nulls the whole list.

Validation

Queries that do not match the schema are answered with errors instead of being partially executed. Among others:

  • unknown fields, arguments, input object fields and directives
  • a selection set on a scalar or enum field, or none on an object field
  • null or a missing value for a non-null argument or variable
  • values of the wrong type, including integers outside the 32-bit Int range
  • fragments that spread themselves, and @skip or @include without a boolean if

Each of these is reported at the field it concerns, with path and locations, and the field is treated like a failed one.

Introspection

The full introspection query generated by current graphql-js, Apollo and GraphiQL is supported, including __type(name:), specifiedByURL, isOneOf, isRepeatable, deprecated arguments and input fields, and subscriptionType.