How to Handle Errors in GraphQL: Simple Guide

In GraphQL, errors are handled by returning an errors array alongside the data in the response. You can throw errors inside resolvers, and use custom error handling middleware or formatters to control error messages sent to clients.

Why This Happens

Errors occur in GraphQL when something goes wrong inside a resolver, such as a failed database query or invalid input. If you don't handle these errors properly, the client may receive unclear or incomplete responses.

javascript

const resolvers = {
  Query: {
    user: (parent, args, context) => {
      // Simulate an error
      throw new Error('User not found');
    }
  }
};

Output

{
  "data": {
    "user": null
  },
  "errors": [
    {
      "message": "User not found",
      "locations": [{ "line": 2, "column": 3 }],
      "path": ["user"]
    }
  ]
}

The Fix

To fix error handling, catch errors inside resolvers and return meaningful messages. You can also use formatError in your GraphQL server setup to customize error output for clients.

javascript

const { ApolloServer, gql } = require('apollo-server');

const typeDefs = gql`
  type Query {
    user(id: ID!): String
  }
`;

const resolvers = {
  Query: {
    user: (parent, args) => {
      if (args.id !== '1') {
        throw new Error('User not found');
      }
      return 'Alice';
    }
  }
};

const server = new ApolloServer({
  typeDefs,
  resolvers,
  formatError: (err) => {
    // Customize error message
    return {
      message: err.message,
      code: err.extensions?.code || 'INTERNAL_SERVER_ERROR'
    };
  }
});

server.listen().then(({ url }) => {
  console.log(`Server ready at ${url}`);
});

Output

{
  "data": null,
  "errors": [
    {
      "message": "User not found",
      "code": "INTERNAL_SERVER_ERROR"
    }
  ]
}

Prevention

To avoid error issues in GraphQL, always validate inputs before processing, use try-catch blocks in resolvers, and implement centralized error formatting. Use libraries like apollo-server that support formatError for consistent error responses.

• Validate inputs early
• Throw clear, descriptive errors
• Use centralized error formatting
• Log errors for debugging

Related Errors

Common related errors include:

• Validation errors: Occur when inputs don't meet schema requirements.
• Authentication errors: When user credentials are missing or invalid.
• Resolver crashes: Unhandled exceptions inside resolvers causing server errors.

Quick fixes involve input validation, authentication checks, and wrapping resolver code in try-catch blocks.

Key Takeaways

Throw errors inside resolvers to signal problems to clients.

Use formatError to customize error messages sent by your GraphQL server.

Validate inputs and handle exceptions to prevent unexpected crashes.

Provide clear, user-friendly error messages for better client experience.

Log errors on the server side to help with debugging and monitoring.