Service capabilities / error behaviors #1163

benjie · 2025-04-30T11:06:37Z

This is a rewrite of

Allow clients to disable error propagation via request parameter #1153

It is re-implemented on top of the recent editorial work (e.g. renaming _field error_ to _execution error_) and also makes a significant change in that it does not require onError to be included in the response, instead an introspection field is used to indicate:

that onError is supported
what the behavior will be if onError is not present

Replaces:

GraphQL.js implementation:

Implement onError proposal graphql-js#4364

Please see this 60 second video on the motivation for this PR (the last few seconds of the video also covers "transitional non-null" which is a separate concern).

As agreed at the nullability working group, disabling error propagation is the future of error handling in GraphQL. Error propagation causes a number of issues, but chief among them are:

It destroys useful data in the response.
It makes it unsafe to store resulting data in normalized stores.

Clients such as Relay do not want error propagation to be a thing.

This has traditionally resulted in schema design best practices advising using nullable in positions where errors were expected, even if null was never a semantically valid value for that position. And since errors can happen everywhere, this has lead to an explosion of nullability and significant pain on the client side with developers having to do seemingly unnecessary null checks in loads of positions, or worse - unsafely bypassing the type safety.

The reason that GraphQL does error propagation is to keep it's "not null" promise in the event that an error occurs (and is replaced with null due to the way GraphQL responses are structured and limitations in JSON) in a non-nullable position.

It doesn't take much code on the client to prevent the client reading a null that relates to an error, graphql-toe can be used with almost any JavaScript or TypeScript based GraphQL client (not Relay, but it has @throwOnFieldError that you can use instead) and achieves this in 512 bytes gzipped - and that's with a focus on performance rather than bundle size.

This PR allows the client to take responsibility for error handling by specifying onError: "NO_PROPAGATE" as part of the GraphQL request, and thereby turns off error propagation behavior. This is also set as the recommended default for future schemas.

With clients responsible for error handling, we no longer need to factor the possibility of whether something can error or not into its nullability, meaning we can use the not-null ! to indicate all the positions in the schema for which null is not a semantically valid value - i.e. the underlying resource will never be a legitimate null.

The end result:

true nullability indicated in schema - no more thinking about where errors are likely
fewer null checks on clients
clients can leverage their native error handling capabilities such as try/catch or <ErrorBoundary />
safe to store errored responses into normalized stores

I've also included onError: "HALT" in this proposal. We've discovered that there's a small but significant class of clients out there, mostly ad-hoc scripts, that throw away the entire response when any error occurs. By codifying this into the spec we make it easier to implement these clients, and we allow the server to halt processing the rest of the request unnecessarily.

As noted by @revangen in this comment:

I've also included onError: ~~"ABORT"~~ "HALT" in this proposal.

Appreciate this being included. For Shopify's public Admin GraphQL API, we have a mix of scenarios that result in a partial success response and only error response. Having been around for 8+ years, we are reluctant at times to change its behaviour to favour partial responses as we don't control majority of clients. Providing clients a way to specify the server's behaviour provides a migration path should clients care about partial responses.

netlify · 2025-04-30T11:06:55Z

✅ Deploy Preview for graphql-spec-draft ready!

Name	Link
🔨 Latest commit	`b5f64ae`
🔍 Latest deploy log	https://app.netlify.com/projects/graphql-spec-draft/deploys/682f8163109ded00087743eb
😎 Deploy Preview	https://deploy-preview-1163--graphql-spec-draft.netlify.app
📱 Preview on mobile	Toggle QR Code... Use your smartphone camera to open QR code link.

To edit notification comments on pull requests, go to your Netlify project configuration.

benjie · 2025-04-30T11:43:22Z

I have applied the RFC1 label to this as inherited from the PR it replaces:

Allow clients to disable error propagation via request parameter #1153

benjie · 2025-04-30T13:52:44Z

A full, CI-passing, implementation of this is available in GraphQL.js now; check it out: graphql@canary-pr-4364

martinbonnin · 2025-04-30T14:20:33Z

spec/Section 4 -- Introspection.md

+enum __ErrorBehavior {
+  NO_PROPAGATE
+  PROPAGATE
+  ABORT


Moving my previous comment here, love this proposal overall but I would love it even more with NULL

enum __ErrorBehavior { NULL PROPAGATE ABORT }

tldr: I believe this is going to be read and discussed a lot more than it's going to be written by users and I would optimize for the conciseness, pronouncability and memorability of NULL.

To summarize my thoughts on it from the previous thread: NULL is what I originally wrote, I agree it looks and initially feels nicer; but ultimately I discounted it for a number of reasons:

Communication issues

If you tell someone on the phone to set onError: NULL, they're very likely to instead set onError: null.

Ambiguity issues

onError: null and onError: NULL are very similar, but the first means PROPAGATE and the latter means NO_PROPAGATE. This is likely to be the source of many user errors and much frustration (both for newbies, and for the people supporting them including library authors).

Errors already become null in the spec:

[an error] raised [...] is handled as though the response position [...] resolved to null
-- https://spec.graphql.org/draft/#sel-FANVNJCAACGW-qR

onError: NULL doesn't implicitly seem to mean something different from this.

Please suggest other alternatives!

I'm very open to changing the word NO_PROPAGATE to something else, I really don't like NO_PROPAGATE, not least because I always want to spell it propOgate rather than propAgate. But I think changing it to NULL would be a mistake.

I've gone through about 30 alternatives when brainstorming it, and none are sufficiently clear whilst also being shorter than NO_PROPAGATE. My favourite alternatives are things like LOCAL/LOCALIZE/ISOLATE/CONTAIN, but I'm not sure they convey the meaning quite as well as NO_PROPAGATE does.

Ooo... Maybe LOCAL_NULL actually is quite compelling. Not thought of that one before.

spec/Section 6 -- Execution.md

fotoetienne · 2025-04-30T19:27:18Z

spec/Section 3 -- Type System.md

+### @behavior
+
+```graphql
+directive @behavior(onError: __ErrorBehavior! = PROPAGATE) on SCHEMA


Thoughts on directive @onError(behavior: __ErrorBehavior!) on SCHEMA to mirror the naming of the client onError field?

Here’s why I think it should be a request parameter and not a directive. (Further, I don’t think we should allow both because that opens up questions around what happens if the client sets one and the user sets the other: who wins?)

What about defining the server default onError behavior only in introspection and not in the SDL? We can instead define abstract "execution configuration" parameters that informs execution behavior. Implementations can then choose to have this be configured via a schema directive or as a separate configuration file.

GraphQLConf requires speakers to be familiar with "inclusive naming", and the inclusive naming guides encourage the avoidance of the word "abort" where possible: https://inclusivenaming.org/word-lists/tier-1/abort/

benjie · 2025-05-22T20:07:04Z

This PR description is currently out of date; I've reworked the capabilities infrastructure based on Lee's feedback, see the changes for details.

martinbonnin · 2025-05-25T18:09:27Z

@benjie @leebyron given the previous discussions on feature discovery have been going on for years, I'm doubtful we can land __Capability soon... Yet onError is crucially needed to move the nullability proposals, is there any chance we could use a new introspection field (__Schema.defaultErrorBehaviour) instead? Or should we expedite __Capability in a separate proposal first? (I'm down with that FWIW)

benjie · 2025-05-25T18:35:19Z

@martinbonnin You don’t like this proposal?

martinbonnin · 2025-05-26T08:21:56Z

@benjie Don't get me wrong, I like __Capability! It's just something that has been discussed before in the community. For an example, it's relatively similar to https://github.com/graphql/graphql-wg/blob/main/rfcs/FeatureDiscovery.md. Feels like getting __Capability through the finish line is probably going to require a much wider discussion and wait times (the time for everyone potentially affected to review __Capability).

While I think onResponse is in a much better spot of being fast tracked.

Of course, I'm all for having both of them. If we want to do that, I think it'd make sense to merge __Capability first and then have onError use that as __Capability solves a more general problem.

In a perfect world, we can land both __Capability and onError in the next couple of months.

martinbonnin · 2025-05-27T22:16:49Z

spec/Section 4 -- Introspection.md

+
+The `__Service` type is returned from the `__service` meta-field and provides
+information about the GraphQL service, most notably about its capabilities. This
+type was added after the original release of GraphQL, so older schemas may not
+support it.


Do we really need the __service indirection vs having __capabilities?
My mental model is that the endpoint is the service. It has a __schema and __capabilities are at the same level (except capabilities can't be expressed in terms of type system).

martinbonnin · 2025-05-27T22:18:23Z

spec/Section 4 -- Introspection.md

+must contain only ASCII letters, digits and hyphens. These constraints are
+inspired by reverse domain name notation to encourage global uniqueness and
+collision-resistance. Unlike the domain name system, capability identifiers are


I like this!

martinbonnin · 2025-05-27T22:36:08Z

spec/Section 4 -- Introspection.md

+- {"org.graphql.defaultErrorBehavior"} - indicates the _default error behavior_
+  of the service via the {value}. If not present, must be assumed to be
+  {"PROPAGATE"}.
+- {"org.graphql.onError"} - indicates that the service allows the client to
+  specify {onError} in a request to indicate the _error behavior_ the service
+  should use for the request. {value} is {null}.


What about this?

Suggested change

- {"org.graphql.defaultErrorBehavior"} - indicates the _default error behavior_

of the service via the {value}. If not present, must be assumed to be

{"PROPAGATE"}.

- {"org.graphql.onError"} - indicates that the service allows the client to

specify {onError} in a request to indicate the _error behavior_ the service

should use for the request. {value} is {null}.

- {"org.graphql.defaultErrorBehavior"} - indicates the _default error behavior_

of the service via the {value}.

If present, the service must be assumed to support the {onError} parameter

to indicate the _error behavior_ on requests.

If not present, must be assumed to be {"PROPAGATE"}.

Less invalid cases possible.

benjie added 2 commits April 30, 2025 11:46

Detail onError request parameter

31c90e7

Detail introspection changes

f4fab96

Define the directive

692d811

benjie marked this pull request as ready for review April 30, 2025 11:41

benjie mentioned this pull request Apr 30, 2025

Allow clients to disable error propagation via request parameter #1153

Closed

benjie added the 💡 Proposal (RFC 1) RFC Stage 1 (See CONTRIBUTING.md) label Apr 30, 2025

This was referenced Apr 30, 2025

Implement onError proposal graphql/graphql-js#4364

Draft

Allow schema @behavior(onError: ...) without explicit root operations #1164

Open

martinbonnin reviewed Apr 30, 2025

View reviewed changes

benjie mentioned this pull request Apr 30, 2025

Add Transitional Non-Null appendix (@noPropagate directive) #1165

Open

fotoetienne reviewed Apr 30, 2025

View reviewed changes

spec/Section 6 -- Execution.md Show resolved Hide resolved

fotoetienne reviewed Apr 30, 2025

View reviewed changes

benjie mentioned this pull request May 1, 2025

Enable 'schema' keyword to be provided without root operations #1166

Closed

benjie added 11 commits May 15, 2025 13:27

ABORT -> HALT

94446ab

GraphQLConf requires speakers to be familiar with "inclusive naming", and the inclusive naming guides encourage the avoidance of the word "abort" where possible: https://inclusivenaming.org/word-lists/tier-1/abort/

Start speccing out the capabilities system

3c63355

Add a number of basic capabilities

7056690

Move default error behavior to the service

0fa7a33

Rework capabilities

1f975e4

Use a definition

8c40086

Reorder

641a786

Reword

026982b

Editorial

a7c6ad5

More editorial

fe559ea

More editorial

b5f64ae

benjie changed the title ~~Allow clients to disable error propagation via request parameter (take 2)~~ Service capabilities / error behaviors May 22, 2025

dondonz mentioned this pull request May 27, 2025

Tracking spec change: service capabilities graphql-java/graphql-java#3992

Open

martinbonnin reviewed May 27, 2025

View reviewed changes

Service capabilities / error behaviors #1163

Are you sure you want to change the base?

Service capabilities / error behaviors #1163

Conversation

benjie commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

netlify bot commented Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

✅ Deploy Preview for graphql-spec-draft ready!

Uh oh!

benjie commented Apr 30, 2025

Uh oh!

benjie commented Apr 30, 2025

Uh oh!

martinbonnin Apr 30, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie Apr 30, 2025

Choose a reason for hiding this comment

Communication issues

Ambiguity issues

Errors already become null in the spec:

Please suggest other alternatives!

Uh oh!

benjie Apr 30, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

fotoetienne Apr 30, 2025

Choose a reason for hiding this comment

Uh oh!

benjie May 1, 2025

Choose a reason for hiding this comment

Uh oh!

fotoetienne May 1, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

benjie commented May 22, 2025

Uh oh!

martinbonnin commented May 25, 2025

Uh oh!

benjie commented May 25, 2025

Uh oh!

martinbonnin commented May 26, 2025

Uh oh!

martinbonnin May 27, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

martinbonnin May 27, 2025

Choose a reason for hiding this comment

Uh oh!

martinbonnin May 27, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

benjie commented Apr 30, 2025 •

edited

Loading

netlify bot commented Apr 30, 2025 •

edited

Loading

martinbonnin Apr 30, 2025 •

edited

Loading

fotoetienne May 1, 2025 •

edited

Loading

martinbonnin May 27, 2025 •

edited

Loading