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:
ExceptionGraphQL 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
causeinstead).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 theoriginal_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
causeargument; 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
causewhen 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
- original_error: Exception | None
Original error that caused this GraphQLError, if one exists
Deprecated since version 3.3: Use
causeinstead 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:
GraphQLErrorA 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
causewhen 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
causeinstead 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:
TypedDictFormatted 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
paththat 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']