Relay Error Handling Project

[itamark]

Relay Error Handling Project

TL;DR

We are proposing a way for engineers to have a safer, more controlled approach to handling GraphQL field errors in Relay.
The proposal includes the ability to specify how you want errors to be handled on fields - potentially including throwing, returning the error along with successful fields, and an option to preserve the current behavior.
These changes are meant to prevent inaccurate client behavior in cases where an error occurs on a field server-side, as well as more granular control over a user’s experience when something does go wrong.

Problem

A feature of GraphQL is that it coalesces errors to null, providing errors as metadata instead of directly throwing exceptions at the network level. Here are some issues that arise from this behavior:
An ecosystem-wide tradeoff (ecosystem-wide because no GraphQL client has addressed this before):

• Discard queries with errors or,
• Not be able to discern whether a null is error or not

Essentially, this leaves users with a choice between:

• Robustness: meaning, “render at all costs” - so if one field errors, everything still returns and that field is null, or
  • This choice leaves users unable to delineate between errors and true nulls.
  • Users also forget that this is how Relay works - even after they’ve learned about it - and fail to account for that edge case.
• Correctness: meaning, if something errors, the query throws and nothing is rendered - so that partially incorrect info never shows.

An additional severe pitfall is that some client-side data could write back incorrect info to the server. So if a field errors and is coalesced to 0 (from null) - it could potentially write back incorrect data to the server.

Our Proposed Solution

We are planning on introducing the ability to define how you want an erroring field to behave - giving users the flexibility to either define the existing behavior (return null upon server error), throw entirely (essentially rethrowing the server error client-side, to be handled by error boundaries for instance), or provided the error in the response to be handled separately.

We are currently working on ironing out implementation details, ergonomics, and addressing known edge-cases.
It’s important to note that we are taking performance and other concerns seriously.

You can expect to see more details on this project as our design solidifies, and we welcome any comments or questions here.

Thanks!

[sibelius]

have you tried @required https://relay.dev/docs/guides/required-directive/#internaldocs-banner ?

[captbaritone]

have you tried @required https://relay.dev/docs/guides/required-directive/#internaldocs-banner ?

One main goal of this project, which @required does not help with, is to address the fact that users can't currently delineate between true null and null-due-to-error in their components.

Longer term, we see a path where this style of explicit error handling could remove the need for @required in most cases. I'll be making a post about this larger vision soon.

[benjie]

There may be some small overlap between this and the Client Controlled Nullability proposal, e.g. earlier this evening we were discussing "skipping" fields rather than including them as null on error, and potentially using a @skip(on: [ERROR, NULL]) or @skipOnError/@skipOnNull directive:

https://github.com/graphql/client-controlled-nullability-wg/blob/main/notes/2023/2023-08.md

I've uploaded the video from tonights meeting to YouTube but it might take an hour or two to process before it's visible: https://www.youtube.com/watch?v=9XqTNnSLpgs&list=PLP1igyLx8foFPThkIGEUVbne2_DBwgQke

I look forward to reading your post, Jordan!

[itamark]

There may be some small overlap between this and the Client Controlled Nullability proposal,

Hi @benjie! Thanks for the link to the meeting. I'll watch it.

Yes, these proposals are definitely related. Thanks to Matt, we were made aware of it early in the design phase. We're actually taking CCN very carefully into consideration to make sure this proposal includes sane interop.

We are planning to attend the graphql wg monthly in September to discuss this, and by then @captbaritone will have published his post and we will be able to present not only the direction of our proposal, but the interop concerns and solutions with CCN.

[mjmahone]

One note on the "render at all costs" current state: not only do you end up attempting to render a surface with an error, you also do not necessarily know the blast radius of the coalesced error. Example:

{
  me {
    ...HasName
    ...HasBestFriend
  }
}
fragment HasName on User {
  name
}
fragment HasBestFriend on User {
  bestFriend {
    ...HasName
  }
}

and a type system like:

type Query {
  me: User
}
type User {
  name: String!
  bestFriend: User!
}

If we have an error on me.bestFriend.name, the response would end up like:

{
  "data": {
    "me": null
  },
  "errors": [{
    "message": "NoName!",
    "path": ["me", "bestFriend", "name"]
  }]
}

Even though we could still render a UI showing the user's name, and even though there is a valid bestFriend, because of the way errors bubble today, the response makes this impossible. And if not handled well, we could end up poisoning Query.me in the normalized store (setting me to null): if you don't set me to null then at render/data-read time, you'll be reading out old (potentially empty/unrelated-to-your-request) data, but if you do then you'll cause all other surfaces making a Query.me request to rerender.

[captbaritone]

@benjie

I look forward to reading your post, Jordan!

I put together a detailed writeup here: graphql/nullability-wg#19

Sorry for the length. Would be very curious to hear your thoughts if/when you have a chance to read it.

[benjie]

As an update to the above; @captbaritone's post spawned a lot of thought and heavy discussions at GraphQLConf. Skipping over all the intermediate results (interrobang and asterisk), it has led to two competing but similar solutions:

• Lee Byron's Strict Semantic Nullability
• My Semantic-Non-Null type

Both of these introduce a way for a field to indicate that it is "null only on error" - i.e. it will never be null unless there's an associated error in the errors list. Mostly they differ in syntax. Lee's version has a global toggle between two modes (via the @strictNullability directive on the schema itself) which changes the meaning of an unadorned type Type to not allow semantic nulls (instead, nullable type would now be Type?). My solution is purely additive in nature (introducing !Type as a semantic non-null type) and does not change the meaning of the unadorned type Type, thus not requiring a toggle.

In the wake of this, the Client Controlled Nullability WG has opted to rename itself to the Nullability WG and has put CCN work on hold whilst we explore the semantic nullability questions.

Thanks again for your excellent write up @captbaritone! 🙌