graphql-middleware-error-handler

1.0.2 verified Sat Apr 25 auth: no javascript

A generic GraphQL middleware that captures errors thrown in resolvers and forwards them to a custom logging function (e.g., Sentry, Bugsnag). Version 1.0.2 is the current stable release; maintenance is intermittent. Key differentiators: minimal API with only three options (onError, captureReturnedErrors, forwardErrors), works with any GraphQL server supporting graphql-middleware (v2–v6), and allows control over error rethrowing and returning error capture.

Common errors

error TypeError: (0 , graphql_middleware_error_handler.errorHandler) is not a function ↓

cause Importing the package incorrectly as a default export instead of a named export.

fix

Use named import: import { errorHandler } from 'graphql-middleware-error-handler'

error errorHandler is not a function (when using require) ↓

cause Using require('...') without destructuring the named export.

fix

Use const { errorHandler } = require('graphql-middleware-error-handler')

error Cannot find module 'graphql-middleware' ↓

cause Missing peer dependency 'graphql-middleware'. The package does not install it automatically.

fix

Run: npm install graphql-middleware

error The 'onError' option is required but was not provided. ↓

cause Creating the errorHandler without passing the required onError callback.

fix

Pass an object with an onError property: errorHandler({ onError: (err, ctx) => { /* ... */ } })

Warnings

gotcha The errorHandler middleware must be placed after other middlewares that may throw; otherwise, those errors won't be captured. ↓

fix Order middlewares correctly: [otherMiddlewares, errorHandlerMiddleware].

gotcha If forwardErrors is false (default), caught errors are swallowed and not returned to the client. This may hide issues in development. ↓

fix Set forwardErrors: true in development or use a different logging strategy.

gotcha The onError callback receives the original error, which may include sensitive information (stack traces, internal messages). Be cautious when logging. ↓

fix Sanitize error object before sending to external services.

deprecated graphql-middleware v2 may have compatibility issues with newer GraphQL servers; the peer dependency range is 2.x - 6.x. ↓

fix Ensure your graphql-middleware version is within 2.x–6.x. Upgrade if necessary.

gotcha captureReturnedErrors only works if the resolver returns an instance of Error. Non-Error objects are not captured. ↓

fix Ensure resolvers throw Error instances or return them directly if captureReturnedErrors is enabled.

Install

npm install graphql-middleware-error-handler

yarn add graphql-middleware-error-handler

pnpm add graphql-middleware-error-handler

Imports

errorHandler

wrong

import errorHandler from 'graphql-middleware-error-handler'

correct

import { errorHandler } from 'graphql-middleware-error-handler'

The package exports a named function, not a default export. Use named import.

ErrorHandlerOptions
```
import { ErrorHandlerOptions } from 'graphql-middleware-error-handler'
```
Type import available if using TypeScript. Useful for type-checking the options object.

ErrorMiddlewareFn

wrong

import { ErrorMiddlewareFn } from 'graphql-middleware-error-handler'

correct

import type { ErrorMiddlewareFn } from 'graphql-middleware-error-handler'

In TypeScript, use 'import type' for the type, as it is not a runtime value.

errorHandler
wrong
```
const errorHandler = require('graphql-middleware-error-handler')
```
correct
```
const { errorHandler } = require('graphql-middleware-error-handler')
```
With CommonJS (require), destructure to get the named export. The package is ESM-first but works with CJS via bundlers.

Quickstart

Sets up a GraphQL server with graphql-yoga and errorHandler middleware that logs errors to console instead of throwing.

import { errorHandler } from 'graphql-middleware-error-handler';
import { GraphQLServer } from 'graphql-yoga';

const typeDefs = `
  type Query {
    hello: String!
    error: String!
  }
`;

const resolvers = {
  Query: {
    hello: () => 'Hello',
    error: () => { throw new Error('Unexpected error'); }
  }
};

const errorHandlerMiddleware = errorHandler({
  onError: (error, context) => {
    console.error('Captured error:', error.message);
  },
  captureReturnedErrors: true,
  forwardErrors: false
});

const server = new GraphQLServer({
  typeDefs,
  resolvers,
  middlewares: [errorHandlerMiddleware]
});

server.start(() => console.log('Server running'));