Error Handling

Whether you're merging types, using schema extensions, or simply combining schemas, any errors returned by a subschema will flow through the stitching process and report at their mapped output positions. It's fairly seamless to provide quality errors from a stitched schema by following some basic guidelines:

1. Report errors! Having a subschema return null without an error for missing or failed records is a poor development experience, to begin with. This omission will compound should an unexpected value produce a misleading failure in gateway stitching. Reporting proper GraphQL errors (opens in a new tab) will contextualize failures in subschemas, and by extension, within the stitched schema.

2. Map errors to array positions. When returning arrays of records (a common pattern while batch loading), make sure to return errors for specific array positions rather than erroring out the entire array. For example, an array should be resolved as:

posts() {
  return [
    { id: '1', ... },
    new GraphQLError('Record not found', {
      extensions: {
        code: 'NOT_FOUND',
      },
    }),
    { id: '3', ... }
  ];
}

1. Assure valid error paths. The GraphQL errors spec (opens in a new tab) prescribes a path attribute mapping an error to its corresponding document position. Stitching uses these paths to remap subschema errors into the combined result. While GraphQL libraries should automatically configure this path for you, the accuracy may vary by programming language (opens in a new tab).