Error

GraphQL Errors

The graphql.error package is responsible for creating and formatting GraphQL errors.

class graphql.error.GraphQLError(message: str, nodes: Collection[Node] | Node | None = None, source: Source | None = None, positions: Collection[int] | None = None, path: Collection[str | int] | None = None, original_error: Exception | None = None, extensions: GraphQLErrorExtensions | None = None, cause: Any = Undefined)

Bases: Exception

GraphQL Error

A GraphQLError describes an Error found during the parse, validate, or execute phases of performing a GraphQL operation. In addition to a message, it also includes information about the locations in a GraphQL document and/or execution result that correspond to the Error.

Parameters:
  • message – Human-readable error message.

  • nodes – AST node or nodes associated with this error.

  • source – Source document used to derive error locations.

  • positions – Character offsets in the source document associated with this error.

  • path – Response path where this error occurred during execution.

  • original_error – Original error that caused this GraphQLError, if one exists (deprecated, use cause instead).

  • extensions – Extension fields to include in the formatted error.

  • cause – The cause of this error, if one exists. It is also exposed as the standard exception __cause__ when it is an exception. Defaults to the original_error.

Create an error from AST nodes and response metadata:

>>> from graphql import GraphQLError, parse
>>> document = parse('{ greeting }')
>>> field_node = document.definitions[0].selection_set.selections[0]
>>> error = GraphQLError(
...     'Cannot query this field.',
...     nodes=field_node,
...     path=['greeting'],
...     extensions={'code': 'FORBIDDEN'},
... )
>>> error.message
'Cannot query this field.'
>>> error.locations
[SourceLocation(line=1, column=3)]
>>> error.path
['greeting']
>>> error.extensions
{'code': 'FORBIDDEN'}

This variant derives locations from source positions and preserves the original error:

>>> from graphql import Source
>>> source = Source('{ greeting }')
>>> original_error = RuntimeError('Database unavailable.')
>>> error = GraphQLError(
...     'Resolver failed.',
...     source=source,
...     positions=[2],
...     path=['greeting'],
...     original_error=original_error,
... )
>>> error.locations
[SourceLocation(line=1, column=3)]
>>> error.path
['greeting']
>>> error.original_error is original_error
True

The cause can also be passed with the cause argument; an exception cause is exposed as the standard exception cause and as the original error:

>>> error = GraphQLError('Resolver failed.', cause=original_error)
>>> error.cause is error.__cause__ is error.original_error is original_error
True

All arguments can also be passed positionally:

>>> error = GraphQLError(
...     'Resolver failed.',
...     None,
...     source,
...     [2],
...     ['greeting'],
...     original_error,
...     {'code': 'INTERNAL'},
... )
>>> error.locations
[SourceLocation(line=1, column=3)]
>>> error.extensions
{'code': 'INTERNAL'}
add_note(note, /)

Add a note to the exception

args
cause: Any

The cause of this error, if one exists

The value passed as the cause when creating this error. Adopts the convention of the standard exception cause and is also exposed as the __cause__ when it is an exception.

extensions: GraphQLErrorExtensions | None

Extension fields to add to the formatted error

property formatted: GraphQLFormattedError

Get error formatted according to the specification.

Given a GraphQLError, format it according to the rules described by the “Response Format, Errors” section of the GraphQL Specification.

>>> from graphql import GraphQLError
>>> error = GraphQLError(
...     'Resolver failed.',
...     path=['viewer', 'name'],
...     extensions={'code': 'INTERNAL'},
... )
>>> error.formatted
{'message': 'Resolver failed.', 'path': ['viewer', 'name'],
 'extensions': {'code': 'INTERNAL'}}
locations: list[SourceLocation] | None

Source locations

A list of (line, column) locations within the source GraphQL document which correspond to this error.

Errors during validation often contain multiple locations, for example to point out two things with the same name. Errors during execution include a single location, the field which produced the error.

message: str

A message describing the Error for debugging purposes

nodes: list[Node] | None

A list of GraphQL AST Nodes corresponding to this error

original_error: Exception | None

Original error that caused this GraphQLError, if one exists

Deprecated since version 3.3: Use cause instead to better align with the standard exception __cause__.

path: list[str | int] | None

Response path

A list of field names and array indexes describing the JSON-path into the execution response which corresponds to this error.

Only included for errors during execution.

positions: Collection[int] | None

Error positions

A list of character offsets within the source GraphQL document which correspond to this error.

source: Source | None

The source GraphQL document for the first location of this error

Note that if this Error represents more than one node, the source may not represent nodes after the first node.

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

class graphql.error.GraphQLSyntaxError(source: Source, position: int, description: str)

Bases: GraphQLError

A GraphQLError representing a syntax error.

Contains useful descriptive information about the syntax error’s position in the source.

Parameters:
  • source – The GraphQL source containing the syntax error.

  • position – Character offset where the syntax error was encountered.

  • description – Human-readable description of the syntax error.

>>> from graphql import GraphQLSyntaxError, Source
>>> error = GraphQLSyntaxError(Source('query {'), 7, 'Expected Name')
>>> error.message
'Syntax Error: Expected Name'
>>> error.locations
[SourceLocation(line=1, column=8)]
add_note(note, /)

Add a note to the exception

args
cause

The cause of this error, if one exists

The value passed as the cause when creating this error. Adopts the convention of the standard exception cause and is also exposed as the __cause__ when it is an exception.

extensions

Extension fields to add to the formatted error

property formatted: GraphQLFormattedError

Get error formatted according to the specification.

Given a GraphQLError, format it according to the rules described by the “Response Format, Errors” section of the GraphQL Specification.

>>> from graphql import GraphQLError
>>> error = GraphQLError(
...     'Resolver failed.',
...     path=['viewer', 'name'],
...     extensions={'code': 'INTERNAL'},
... )
>>> error.formatted
{'message': 'Resolver failed.', 'path': ['viewer', 'name'],
 'extensions': {'code': 'INTERNAL'}}
locations

Source locations

A list of (line, column) locations within the source GraphQL document which correspond to this error.

Errors during validation often contain multiple locations, for example to point out two things with the same name. Errors during execution include a single location, the field which produced the error.

message

A message describing the Error for debugging purposes

nodes

A list of GraphQL AST Nodes corresponding to this error

original_error

Original error that caused this GraphQLError, if one exists

Deprecated since version 3.3: Use cause instead to better align with the standard exception __cause__.

path

Response path

A list of field names and array indexes describing the JSON-path into the execution response which corresponds to this error.

Only included for errors during execution.

positions

Error positions

A list of character offsets within the source GraphQL document which correspond to this error.

source

The source GraphQL document for the first location of this error

Note that if this Error represents more than one node, the source may not represent nodes after the first node.

with_traceback(tb, /)

Set self.__traceback__ to tb and return self.

class graphql.error.GraphQLFormattedError

Bases: TypedDict

Formatted GraphQL error

See: https://spec.graphql.org/draft/#sec-Errors

extensions: GraphQLFormattedErrorExtensions

Custom extensions.

Reserved for implementors to extend the protocol however they see fit, and hence there are no additional restrictions on its contents.

locations: list[FormattedSourceLocation]

Locations in the requested GraphQL document.

If an error can be associated to a particular point in the requested GraphQL document, it should contain a list of locations.

message: str

A short, human-readable summary of the problem.

The message SHOULD NOT change from occurrence to occurrence of the problem, except for purposes of localization.

path: list[str | int]

Path of the response field which experienced the error.

If an error can be associated to a particular field in the GraphQL result, it must contain an entry with the key path that details the path of the response field which experienced the error. This allows clients to identify whether a null result is intentional or caused by a runtime error.

graphql.error.located_error(original_error: Exception, nodes: Collection[Node] | None = None, path: Collection[str | int] | None = None) → GraphQLError

Located GraphQL Error

Given an arbitrary Exception, presumably thrown while attempting to execute a GraphQL operation, produce a new GraphQLError aware of the location in the document responsible for the original Exception.

Parameters:
  • original_error – The original error value to wrap.

  • nodes – The AST nodes associated with the error.

  • path – The response path associated with the error.

Returns:

The GraphQL error.

>>> from graphql import located_error, parse
>>> document = parse('{ viewer { name } }')
>>> field_node = document.definitions[0].selection_set.selections[0]
>>> error = located_error(RuntimeError('Resolver failed'), [field_node], ['viewer'])
>>> error.message
'Resolver failed'
>>> error.locations
[SourceLocation(line=1, column=3)]
>>> error.path
['viewer']