Error Handling

Apollo Server v4 introduced a regression where providing invalid variables yields a 200 status code instead of 400. To mitigate this regression, provide the status400ForVariableCoercionErrors: true option to your ApolloServer constructor. For more information, see the migration guide .

Whenever Apollo Server encounters errors while processing a GraphQL operation, its response to the client includes an errors array containing each error that occurred. Each error in the array has an extensions field that provides additional useful information, including an error code and (while in development mode) a stacktrace.

Here's an example error response caused by misspelling the __typename field in a query:

1{
2  "errors": [
3    {
4      "message": "Cannot query field \"__typenam\" on type \"Query\".",
5      "locations": [
6        {
7          "line": 1,
8          "column": 2
9        }
10      ],
11      "extensions": {
12        "code": "GRAPHQL_VALIDATION_FAILED",
13        "stacktrace": [
14          "GraphQLError: Cannot query field \"__typenam\" on type \"Query\".",
15          "    at Object.Field (/my_project/node_modules/graphql/validation/rules/FieldsOnCorrectTypeRule.js:48:31)",
16          "    ...additional lines..."
17        ]
18      }
19    }
20  ]
21}

To help with debugging, Apollo Server provides an ApolloServerErrorCode enum, which you can use to check if your error is one of the different types produced by Apollo Server .

You can check an error's code to determine why an error occurred and also add logic to respond to different types of errors, like so:

1import { ApolloServerErrorCode } from '@apollo/server/errors';
2
3if (error.extensions?.code === ApolloServerErrorCode.GRAPHQL_PARSE_FAILED) {
4  // respond to the syntax error
5} else if (error.extensions?.code === "MY_CUSTOM_CODE") {
6  // do something else
7}

Apollo Server's variety of error codes enables requesting clients to respond differently to different error types. You can also create your own custom errors and codes .

Built-in error codes

Custom errors

You can create a custom errors and codes using the graphql package's GraphQLError class, like so:

1import { GraphQLError } from 'graphql';
2
3throw new GraphQLError(message, {
4  extensions: { code: 'YOUR_ERROR_CODE', myCustomExtensions },
5});

Custom errors can provide additional context, enabling your clients to understand why an error is happening. We recommend making clear errors for common cases, for example, when a user isn't logged in (UNAUTHENTICATED), or someone is forbidden from performing an action:

1import { GraphQLError } from 'graphql';
2
3throw new GraphQLError('You are not authorized to perform this action.', {
4  extensions: {
5    code: 'FORBIDDEN',
6  },
7});

Throwing errors

Apollo Server throws errors automatically when applicable. For example, it throws a GRAPHQL_VALIDATION_FAILED error whenever an incoming operation isn't valid against the server's schema.

Your resolvers can also throw errors in situations where Apollo Server doesn't do so automatically.

For example, this resolver throws a custom error if the integer value provided for a user's ID is less than 1:

1import { GraphQLError } from 'graphql';
2
3const typeDefs = `#graphql
4  type Query {
5    userWithID(id: ID!): User
6  }
7
8  type User {
9    id: ID!
10    name: String!
11  }
12`;
13
14const resolvers = {
15  Query: {
16    userWithID: (_, args) => {
17      // highlight-start
18      if (args.id < 1) {
19        throw new GraphQLError('Invalid argument value', {
20          extensions: {
21            code: 'BAD_USER_INPUT',
22          },
23        });
24      }
25      // highlight-end
26      // ...fetch correct user...
27    },
28  },
29};

If a resolver throws a generic error that is not a GraphQLError instance, that error is still thrown with an extensions field that includes a stacktrace and code (specifically INTERNAL_SERVER_ERROR ), along with any other relevant error details.

Including custom error details

Whenever you throw a GraphQLError, you can add arbitrary fields to the error's extensions object to provide additional context to the client. You specify these fields in an object you provide to the error's constructor.

This example builds on the one above by adding the name of the GraphQL argument that was invalid:

1import { GraphQLError } from 'graphql';
2
3const typeDefs = `#graphql
4  type Query {
5    userWithID(id: ID!): User
6  }
7
8  type User {
9    id: ID!
10    name: String!
11  }
12`;
13
14const resolvers = {
15  Query: {
16    userWithID: (_, args) => {
17      if (args.id < 1) {
18        throw new GraphQLError('Invalid argument value', {
19          // highlight-start
20          extensions: {
21            code: 'BAD_USER_INPUT',
22            argumentName: 'id',
23          },
24          // highlight-end
25        });
26      }
27      // ...fetch correct user...
28    },
29  },
30};

This results in a response like the following: