{"id":18559,"library":"middy-middleware-json-error-handler","title":"Middy JSON Error Handler Middleware","description":"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.","status":"active","version":"4.0.0","language":"javascript","source_language":"en","source_url":"ssh://git@github.com/dbartholomae/middy-middleware-json-error-handler","tags":["javascript","middy","middleware","error","http","json","typescript"],"install":[{"cmd":"npm install middy-middleware-json-error-handler","lang":"bash","label":"npm"},{"cmd":"yarn add middy-middleware-json-error-handler","lang":"bash","label":"yarn"},{"cmd":"pnpm add middy-middleware-json-error-handler","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"peer dependency; required to use this middleware","package":"@middy/core","optional":false}],"imports":[{"note":"The package exports a default function; named import will not work.","wrong":"import { JSONErrorHandlerMiddleware } from 'middy-middleware-json-error-handler'","symbol":"default","correct":"import JSONErrorHandlerMiddleware from 'middy-middleware-json-error-handler'"},{"note":"CommonJS require returns an object with a `default` property since the package is ESM-first.","wrong":"const JSONErrorHandlerMiddleware = require('middy-middleware-json-error-handler')","symbol":"default with require","correct":"const JSONErrorHandlerMiddleware = require('middy-middleware-json-error-handler').default"},{"note":"Options parameter is optional but must be passed as an object if provided.","wrong":".use(JSONErrorHandlerMiddleware())","symbol":"in Middy .use()","correct":".use(JSONErrorHandlerMiddleware(options))"}],"quickstart":{"code":"import middy from '@middy/core';\nimport JSONErrorHandlerMiddleware from 'middy-middleware-json-error-handler';\nimport createError from 'http-errors';\n\nconst baseHandler = async (event) => {\n  const search = event.queryStringParameters?.search;\n  if (!search) {\n    throw createError(400, 'Query must include search');\n  }\n  if (search === 'error') {\n    throw createError(500, 'Internal error', { expose: true });\n  }\n  throw new Error('Search not implemented');\n};\n\nconst handler = middy(baseHandler)\n  .use(JSONErrorHandlerMiddleware({ errorPropertiesToOmit: ['stack'] }));\n\nexport { handler };","lang":"typescript","description":"Creates a Middy handler that uses the JSON error handler middleware to return structured JSON errors."},"warnings":[{"fix":"If you rely on hiding 5xx errors, ensure you do not set `expose` truthy on such errors.","message":"Errors with status >= 500 and `expose` set to truthy will be exposed; previously they were always hidden.","severity":"breaking","affected_versions":">=4.0.0"},{"fix":"Use ESM imports or require with `.default`.","message":"The package is ESM-only from v3 onward; CommonJS require will not work without using `.default`.","severity":"deprecated","affected_versions":">=3.0.0"},{"fix":"Ensure base handler is async and throws synchronously or returns a rejected promise.","message":"The middleware only catches errors thrown; it does not handle async rejections (use Middy's `use` with `await`).","severity":"gotcha","affected_versions":"all"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Use `import JSONErrorHandlerMiddleware from 'middy-middleware-json-error-handler'` (without braces).","cause":"Named import instead of default import","error":"TypeError: (0 , middy_middleware_json_error_handler__WEBPACK_IMPORTED_MODULE_0__) is not a function"},{"fix":"Use `const JSONErrorHandlerMiddleware = require('middy-middleware-json-error-handler').default`","cause":"Using CommonJS require without .default","error":"TypeError: middleware is not a function"},{"fix":"Create a custom error interface extending Error with statusCode or use http-errors.","cause":"TypeScript strict mode; custom error types need explicit statusCode property","error":"Property 'statusCode' does not exist on type 'Error'"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}