GraphQL servers are able to handle errors by default, both for syntax and validations errors. You've probably already seen this when using 

 or any other playground to explore GraphQL APIs. But often the default way is not sufficient for more complex situations or to sophistically handle the errors from a frontend application. So let's dive into how to improve this.

Error handling is described in the GraphQL specification and is part of the default structure of any GraphQL response. This response consists of 3 fields:

The simplest type of error that you can get is when you in example try to use an operation that's not present in the schema of your GraphQL API. Suppose we have an API that serves as the backend for a music application. Using queries and mutations, you will be able to view tracks, add playlists, and save tracks to playlists that you've created.

One of the operations for that API is a mutation to add a track to a playlists, which is called 

saveTrackToPlaylist(input: { playlistId: 1, trackId: 1 }) {
  id
  title
}

But suppose we make a mistake when spelling the mutation in the GraphQL playground. What would happen? The server will throw a default GraphQL error, as the misspelled mutation is not present in the schema:

The response object has the previously mentioned 

Cannot query field \"saveTrrackToPlaylist\" on type \"Mutation\". Did you mean \"saveTrackToPlaylist\"?

. As you can see GraphQL graciously prevents you in sending non-existing operations to the server. Similar errors are thrown when your operation variables or requested fields are incorrect.

When you have an error that's not related to the GraphQL schema, you would have to throw an error from the resolvers of your GraphQL server. This can simpy be done by throwing an error from the resolver. This would looks something like this for the music application server:

async function saveTrackToPlaylist(
  _: any,
  { input }: any,
  { knex }: Context,
): Promise<any> {
  if (!knex) throw new Error('Not connected to the database');

  const { playlistId, trackId } = input;

  const playlist = await knex('playlists').where('id', playlistId).select();
  const track = await knex('tracks').where('id', trackId).select();

  if (!playlist.length) throw new Error('Playlist not found');
  if (!track.length) throw new Error('Track not found');

// ...

}

In the resolver an error is thrown when the playlist or track that you define for the 

 mutation are not present in the database. The error message will again be added to the 

The snippet above has been truncated but the actual response in the GraphQL playground is a huge chunk of JSON, which makes it hard to get the important information from that response.

Fortunately, the GraphQL specification allows you to add a field called 

 object or use predefined error methods available in Apollo Server. Apollo Server provides several predefined errors, such as 

. These errors make it easier for you to debug and read errors from the GraphQL server.

Handling errors this way works especially well when you're using Apollo to create your GraphQL server, but there are more declarative ways of returning errors to the client. One way of doing so is by adding errors as data. This approach has several advantages:

To add errors to your data, you need to use the 

) in your GraphQL schema. Also, the logic in the resolver is rewritten so that next to the result or error for the operation you also need to return a type for it. 

This allows you to send the previous mutation in the following way, which has different payload types based on the return of the resolver. The mutation 

 now has three different payloads depending on the result of the resolver. 

saveTrackToPlaylist(input: { playlistId: 1, trackId: 1 }) {
  ... on SaveTrackSuccess {
    playlistId
    playlistTitle
    trackId
    trackTitle
  }
  ... on SaveTrackPlaylistError {
    playlistId
    message
  }
  ... on SaveTrackError {
    trackId
    message
  }
}

 returns the playlist and tracks details when the operation is successful, while the 

More implementations for error handling in GraphQL and the full source code are available it the book 

<h1 data-node-type="titlePlaceholder" class="titlePlaceholder">Error Handling in GraphQL</h1><p>GraphQL servers are able to handle errors by default, both for syntax and validations errors. You've probably already seen this when using <em>GraphiQL</em> or any other playground to explore GraphQL APIs. But often the default way is not sufficient for more complex situations or to sophistically handle the errors from a frontend application. So let's dive into how to improve this.</p><h2><a name="graphql-error-object" id="graphql-error-object">GraphQL Error Object</a></h2><p>Error handling is described in the GraphQL specification and is part of the default structure of any GraphQL response. This response consists of 3 fields:</p><ul><li><p>The&nbsp;<code>data</code>&nbsp;field, containing the result of the operation</p></li><li><p>The&nbsp;<code>errors</code>&nbsp;field, containing all the errors that occurred during the execution of the operation</p></li><li><p>An optional&nbsp;<code>extensions</code>&nbsp;field that contains meta data about the operation</p></li></ul><p>The simplest type of error that you can get is when you in example try to use an operation that's not present in the schema of your GraphQL API. Suppose we have an API that serves as the backend for a music application. Using queries and mutations, you will be able to view tracks, add playlists, and save tracks to playlists that you've created.</p><p>One of the operations for that API is a mutation to add a track to a playlists, which is called <code>saveTrackToPlaylist</code>. </p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-KJI9r" id="cm-KJI9r">saveTrackToPlaylist(input: { playlistId: 1, trackId: 1 }) {
  id
  title
}</textarea><p>But suppose we make a mistake when spelling the mutation in the GraphQL playground. What would happen? The server will throw a default GraphQL error, as the misspelled mutation is not present in the schema:</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20201112134926285_Screenshot%202020-11-12%20at%2014.36.13.png" attachmentid="cfb4b52e-38a7-40e2-88d3-3505268843c5" contenteditable="false" data-width="2880" data-height="1322"><div></div></figure><p>The response object has the previously mentioned <code>error</code> field and a message stating the error: <code>Cannot query field \"saveTrrackToPlaylist\" on type \"Mutation\". Did you mean \"saveTrackToPlaylist\"?</code>. As you can see GraphQL graciously prevents you in sending non-existing operations to the server. Similar errors are thrown when your operation variables or requested fields are incorrect.</p><p>When you have an error that's not related to the GraphQL schema, you would have to throw an error from the resolvers of your GraphQL server. This can simpy be done by throwing an error from the resolver. This would looks something like this for the music application server:</p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-ol3RE" id="cm-ol3RE">async function saveTrackToPlaylist(
  _: any,
  { input }: any,
  { knex }: Context,
): Promise&lt;any&gt; {
  if (!knex) throw new Error('Not connected to the database');

  const { playlistId, trackId } = input;

  const playlist = await knex('playlists').where('id', playlistId).select();
  const track = await knex('tracks').where('id', trackId).select();

  if (!playlist.length) throw new Error('Playlist not found');
  if (!track.length) throw new Error('Track not found');

// ...

}</textarea><p>In the resolver an error is thrown when the playlist or track that you define for the <code>saveTrackToPlaylist</code> mutation are not present in the database. The error message will again be added to the <code>errors</code> field of the GraphQL response object.</p><figure class="photo figure-position-inline"><img src="https://s3.amazonaws.com/assets.fullstack.io/n/20201112140114840_graphql-playground-error-stacktrace.png" attachmentid="c7a0de50-45d0-4c23-b155-943586521c4b" contenteditable="false" data-width="2880" data-height="1335"><div></div></figure><p>The snippet above has been truncated but the actual response in the GraphQL playground is a huge chunk of JSON, which makes it hard to get the important information from that response.</p><p>Fortunately, the GraphQL specification allows you to add a field called <code>extensions</code> to the <code>error</code> object. To extend the <code>error</code> object, you can either throw a custom <code>Error</code> object or use predefined error methods available in Apollo Server. Apollo Server provides several predefined errors, such as <code>AuthenticationError</code>, <code>ForbiddenError</code>, and <code>UserInputError</code>, as well as the general <code>ApolloError</code>. These errors make it easier for you to debug and read errors from the GraphQL server.</p><h2><a name="data-as-error" id="data-as-error">Data as error</a></h2><p>Handling errors this way works especially well when you're using Apollo to create your GraphQL server, but there are more declarative ways of returning errors to the client. One way of doing so is by adding errors as data. This approach has several advantages:</p><ul><li><p>You no longer have to return <code>null</code> for the payload of the operations in the GraphQL resolver</p></li><li><p>Errors become available in the GraphQL schema, and you can include them in the response.</p></li></ul><p>To add errors to your data, you need to use the <code>Union</code> type (a.k.a. <code>Result</code>) in your GraphQL schema. Also, the logic in the resolver is rewritten so that next to the result or error for the operation you also need to return a type for it. </p><p>This allows you to send the previous mutation in the following way, which has different payload types based on the return of the resolver. The mutation <code>saveTrackToPlaylist</code> now has three different payloads depending on the result of the resolver. </p><textarea data-iscodemirror="true" data-mode="javascript" data-uniqueid="cm-Uyesc" id="cm-Uyesc">saveTrackToPlaylist(input: { playlistId: 1, trackId: 1 }) {
  ... on SaveTrackSuccess {
    playlistId
    playlistTitle
    trackId
    trackTitle
  }
  ... on SaveTrackPlaylistError {
    playlistId
    message
  }
  ... on SaveTrackError {
    trackId
    message
  }
}</textarea><p>The payload <code>SaveTrackSuccess</code> returns the playlist and tracks details when the operation is successful, while the <code>SaveTrackPlaylistError</code> and <code>SaveTrackError</code> are retuned when an error occurs. </p><p>More implementations for error handling in GraphQL and the full source code are available it the book <a href="https://newline.co/fullstack-graphql" rel="noopener noreferrer nofollow">Fullstack GraphQL</a>.</p><p></p><p></p><p></p><p></p><p></p>

Learn

The newline Guide to Building Your First GraphQL Server with Node and TypeScript

Teach

Amelia Wattenberger

Author of Fullstack D3

Community

Error Handling in GraphQL

Responses (0)

Masterclasses

Tutorials

Fullstack React with TypeScript