Error behaviors (including `onError: "NULL"`)

At a glance

• Identifier: #1163
• Stage: RFC 1 / Proposal
• Champion: @benjie
• Latest activity: Top comment edited on 2026-08-06
• Spec PR: https://github.com/graphql/graphql-spec/pull/1163
• Related:
  • #1065
  • #1153

Spec PR description

This is a rewrite of:

• #1153

Service capabilities has been split into:

• #1208

Depending on the order that these are merged, whichever is merged later should add the relevant service capabilities for error behaviors (each are optional):

• graphql.onError: indicates that this service accepts and honors the onError request property
• graphql.defaultErrorBehavior: one of PROPAGATE, NULL or ABORT. Must be set unless the default error behavior is PROPAGATE. Allows creating a new service which uses a different error behavior from the outset. Changing this once a service is in production would be a breaking change.
  • Per the working group on 2026-08-06 we will forever have PROPAGATE as the default error behavior, so this capability has been removed. But worry not! The proposal is that the onError value to use can be incorporated into the trusted documents to save you precious network bytes.

Replaces:

• #1050
• #1145
• #1153

GraphQL.js implementation:

• https://github.com/graphql/graphql-js/pull/4364

Please see this (slightly outdated) 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:

1. It destroys useful data in the response.
2. 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: "NULL" 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.