Registry / aws / middy-middleware-json-error-handler

middy-middleware-json-error-handler

library4.0.0jsnpmunverified

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.

aws web-framework observability

npm install middy-middleware-json-error-handler

github ↗package ↗

INSTALL

IMPORT

SIG · MIDDY-MIDDLEWARE-J

middy-middleware-json-error-handler

awsjavascriptv4.0.0

Install

—

Import

—

Disk

—

Pass rate

0/ 6

Env Coverage0 / 6

glibc

18–22

musl

18–22

Install & Compatibility

Where this runs

tested against v? · npm install

Install × environment matrix

Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux

musl

node 18–226 runs

build_error

glibc

node 18–226 runs

build_error

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

default

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

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

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

default with require

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

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

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

in Middy .use()

✓ .use(JSONErrorHandlerMiddleware(options))

✗ .use(JSONErrorHandlerMiddleware())

Options parameter is optional but must be passed as an object if provided.

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 };

Debug

Known issues

breakingErrors 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.

affects: >=4.0.0

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

fix

Use ESM imports or require with `.default`.

affects: >=3.0.0

gotchaThe 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.

affects: all

Errors

Common errors & fixes

TypeError: (0 , middy_middleware_json_error_handler__WEBPACK_IMPORTED_MODULE_0__) is not a function

Named import instead of default import

fix

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

TypeError: middleware is not a function

Using CommonJS require without .default

fix

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

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

TypeScript strict mode; custom error types need explicit statusCode property

fix

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

Upgrade

Version history

4.0.0latest on npm

Audit

Dependencies

@middy/corerequiredpeer dependency; required to use this middleware

Agent activity

24 hits · last 30 days

node

OpenAI (training)

Resources

githubhttps://github.com/dbartholomae/middy-middleware-json-error-handler ↗

packagehttps://www.npmjs.com/package/middy-middleware-json-error-handler ↗