Middy JSON Error Handler Middleware

4.0.0 verified Sat Apr 25 auth: no javascript

A middleware for the Middy.js Lambda middleware engine that converts thrown errors into structured JSON HTTP responses, compatible with http-errors. Current stable version is 4.0.0 (released 2023-07-26). Follows semantic release, with updates every few months. Key differentiators: automatic JSON serialization, support for http-errors and custom error classes, configurable property omission (stack, name, etc.), and the ability to expose internal errors via the `expose` property even for 5xx responses. Ships TypeScript types.

Common errors

error TypeError: (0 , middy_middleware_json_error_handler__WEBPACK_IMPORTED_MODULE_0__) is not a function ↓

cause Named import instead of default import

fix

Use import JSONErrorHandlerMiddleware from 'middy-middleware-json-error-handler' (without braces).

error TypeError: middleware is not a function ↓

cause Using CommonJS require without .default

fix

Use const JSONErrorHandlerMiddleware = require('middy-middleware-json-error-handler').default

error Property 'statusCode' does not exist on type 'Error' ↓

cause TypeScript strict mode; custom error types need explicit statusCode property

fix

Create a custom error interface extending Error with statusCode or use http-errors.

Warnings

breaking Errors with status >= 500 and `expose` set to truthy will be exposed; previously they were always hidden. ↓

fix If you rely on hiding 5xx errors, ensure you do not set `expose` truthy on such errors.

deprecated The package is ESM-only from v3 onward; CommonJS require will not work without using `.default`. ↓

fix Use ESM imports or require with `.default`.

gotcha The middleware only catches errors thrown; it does not handle async rejections (use Middy's `use` with `await`). ↓

fix Ensure base handler is async and throws synchronously or returns a rejected promise.

Install

npm install middy-middleware-json-error-handler

yarn add middy-middleware-json-error-handler

pnpm add middy-middleware-json-error-handler

Imports

default

wrong

import { JSONErrorHandlerMiddleware } from 'middy-middleware-json-error-handler'

correct

import JSONErrorHandlerMiddleware from 'middy-middleware-json-error-handler'

The package exports a default function; named import will not work.

default with require

wrong

const JSONErrorHandlerMiddleware = require('middy-middleware-json-error-handler')

correct

const JSONErrorHandlerMiddleware = require('middy-middleware-json-error-handler').default

CommonJS require returns an object with a `default` property since the package is ESM-first.

in Middy .use()
wrong
```
.use(JSONErrorHandlerMiddleware())
```
correct
```
.use(JSONErrorHandlerMiddleware(options))
```
Options parameter is optional but must be passed as an object if provided.

Quickstart

Creates a Middy handler that uses the JSON error handler middleware to return structured JSON errors.

import middy from '@middy/core';
import JSONErrorHandlerMiddleware from 'middy-middleware-json-error-handler';
import createError from 'http-errors';

const baseHandler = async (event) => {
  const search = event.queryStringParameters?.search;
  if (!search) {
    throw createError(400, 'Query must include search');
  }
  if (search === 'error') {
    throw createError(500, 'Internal error', { expose: true });
  }
  throw new Error('Search not implemented');
};

const handler = middy(baseHandler)
  .use(JSONErrorHandlerMiddleware({ errorPropertiesToOmit: ['stack'] }));

export { handler };