You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Adds support for proper error handling and partial responses as defined
by the spec, cf. https://spec.graphql.org/September2025/#sec-Errors
KGraphQL now distinguishes between _request_ and _execution_ errors, and
the latter now result in a response that contains both, `data` and
`errors`. Execution errors result in a value of `null` for nullable
fields, and will bubble up to their parent node for non-nullable fields.
Additionally, resolvers can now raise execution errors while still
returning data.
If data _and_ errors are present in the response, the `errors` key is
serialized first to make it more apparent that errors are present.
Behavior for request errors is unchanged, and `wrapErrors` configuration
is still supported for now - but likely subject to change in the future.
Resolves#114
BREAKING CHANGE: relying on exceptions being thrown from query execution
may no longer work as before. It is advised to specify `wrapErrors =
false` and report an issue with the respective use case.
Error handling is currently implemented in a basic way only, and does for example not support multiple errors or partial responses.
3
+
When `wrapErrors` is `true` (which is the default), exceptions encountered during execution of a request will be wrapped, and are returned as part of a well-formed response.
4
4
5
-
## Basics
5
+
## Error Format
6
6
7
-
When an exception occurs, request execution is aborted and results in an error response depending on the type of exception.
7
+
Every error has an entry with the key `message` that contains a human-readable description of the problem.
8
8
9
-
Exceptions that extend `GraphQLError` via either `RequestError` or `ExecutionError` will be mapped to a response that contains
10
-
an `errors` key with optional `locations` and `path` keys detailing where it occurred.
11
-
Sub classes can also provide arbitrary `extensions`, by default an error `type` will be added:
9
+
If an error can be associated to a point in the GraphQL document, it will contain an entry with the key `locations` that lists all lines and columns this error is referring to.
10
+
11
+
If an error can be associated to a particular field, it will contain an entry with the key `path`, containing all segments up to the field where it occurred. This helps clients to distinguish genuine `null` responses from missing values due to errors.
12
+
13
+
Additionally, every error can contain an entry with the key `extensions` that is a map of server-specific additions outside of the schema. All built-in errors will be mapped with a `type` extension according to their class.
14
+
15
+
Depending on the type of error, the response may also contain a `data` key and partial response data.
16
+
17
+
## Request Errors
18
+
19
+
_Request errors_ are errors that result in no response data. They are typically raised before execution begins, and may be caused by parsing errors in the request document, invalid syntax or invalid input values for variables.
20
+
21
+
Request errors are typically the fault of the requesting client.
22
+
23
+
If a request error is raised, the response will only contain an `errors` key with corresponding details.
12
24
13
25
=== "Example"
14
26
```json
15
27
{
16
-
"errors": [
17
-
{
18
-
"message": "Property 'nonexisting' on 'MyType' does not exist",
19
-
"locations": [
20
-
{
21
-
"line": 3,
22
-
"column": 1
23
-
}
24
-
],
25
-
"extensions": {
26
-
"type": "GRAPHQL_VALIDATION_FAILED"
27
-
}
28
-
}
29
-
]
28
+
"errors": [
29
+
{
30
+
"message": "Missing selection set on property 'film' of type 'Film'",
31
+
"extensions": {
32
+
"type": "GRAPHQL_VALIDATION_FAILED"
33
+
}
34
+
}
35
+
]
30
36
}
31
37
```
32
38
33
-
All built-in exceptions extend `GraphQLError`.
39
+
## Execution Errors
34
40
35
-
## Exceptions From Resolvers
41
+
_Execution errors_ (previously called _field errors_ in the spec) are errors raised during execution of a particular field, and result in partial response data. They may be caused by coercion failures or internal errors during function invocation.
36
42
37
-
What happens with exceptions from resolvers depends on the [schema configuration](configuration.md).
43
+
Execution errors are typically the fault of the GraphQL server.
38
44
39
-
### wrapErrors = true
45
+
When an execution error occurs, it is added to the list of errors in the response, and the value of its field is coerced to `null`. If that is a valid value for the field, execution continues with the next sibling. Otherwise, when the field is a non-null type, the error is propagated to the parent field, until a nullable type or the root type is reached.
40
46
41
-
With `wrapErrors = true` (which is the default), exceptions are wrapped as `ExecutionException`, which is a `GraphQLError`:
47
+
Execution errors can lead to partial responses, where some fields can still return proper data. To make partial responses more easily identifiable, the `errors` key will be serialized as first entry in the response JSON.
42
48
43
-
=== "Example"
44
-
```kotlin
45
-
KGraphQL.schema {
46
-
configure {
47
-
wrapErrors = true
49
+
Given the [Star Wars schema](../Tutorials/starwars.md), if fetching one of the friends' names fails in the following operation, the response might contain a friend without a name:
Because thrown exceptions are re-thrown, `wrapErrors = false` will not produce partial responses from thrown exceptions, but resolvers can still return partial responses by calling `Context.raiseError`.
0 commit comments