{"id":18422,"library":"hono-problem-details","title":"hono-problem-details","description":"RFC 9457 Problem Details middleware for Hono that standardizes error responses across routes. Current stable version is 0.5.0, released monthly with semantic versioning. Key differentiators: official Hono integrations for Zod, Valibot, Zod-OpenAPI, and Standard Schema; auto-instance population; localization support; zero runtime dependencies beyond Hono; edge-worker compatible. Alternatives require manual error shaping or lack standard compliance.","status":"active","version":"0.5.0","language":"javascript","source_language":"en","source_url":"https://github.com/paveg/hono-problem-details","tags":["javascript","hono","rfc9457","problem-details","error-handling","middleware","api","openapi","zod","typescript"],"install":[{"cmd":"npm install hono-problem-details","lang":"bash","label":"npm"},{"cmd":"yarn add hono-problem-details","lang":"bash","label":"yarn"},{"cmd":"pnpm add hono-problem-details","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Core framework peer dependency required for middleware integration","package":"hono","optional":false},{"reason":"Optional integration for Zod validation error binding","package":"zod","optional":true},{"reason":"Optional integration for Valibot validation error binding","package":"valibot","optional":true},{"reason":"Optional integration for OpenAPI schema generation","package":"@hono/zod-openapi","optional":true}],"imports":[{"note":"ESM-only export; CommonJS require will not work. Use named import.","wrong":"const problemDetailsHandler = require('hono-problem-details')","symbol":"problemDetailsHandler","correct":"import { problemDetailsHandler } from 'hono-problem-details'"},{"note":"Named export, not default. Correct since v0.1.0.","wrong":"import ProblemDetailsError from 'hono-problem-details'","symbol":"ProblemDetailsError","correct":"import { ProblemDetailsError } from 'hono-problem-details'"},{"note":"Subpath export added in v0.4.0; do not import from root. Only available if zod peer dependency is installed.","wrong":"import { zodProblemDetailsHook } from 'hono-problem-details'","symbol":"zodProblemDetailsHook","correct":"import { zodProblemDetailsHook } from 'hono-problem-details/zod'"},{"note":"Type-only import to avoid runtime issues. Available as type export.","wrong":"import { ProblemDetails } from 'hono-problem-details'","symbol":"ProblemDetails","correct":"import type { ProblemDetails } from 'hono-problem-details'"}],"quickstart":{"code":"import { Hono } from 'hono';\nimport { HTTPException } from 'hono/http-exception';\nimport { problemDetailsHandler, ProblemDetailsError } from 'hono-problem-details';\n\nconst app = new Hono();\n\napp.onError(problemDetailsHandler({ autoInstance: true }));\n\napp.get('/ok', (c) => c.text('OK'));\n\napp.get('/not-found', (c) => {\n  throw new HTTPException(404, { message: 'Resource not found' });\n});\n\napp.get('/custom', (c) => {\n  throw new ProblemDetailsError({\n    status: 422,\n    title: 'Validation Failed',\n    detail: 'The request body is not valid.',\n    extensions: { errors: [{ field: 'username', message: 'required' }] },\n  });\n});\n\napp.get('/error', (c) => {\n  throw new Error('Something went wrong');\n});\n\nexport default app;","lang":"typescript","description":"Hono app with problemDetailsHandler error middleware showing RFC 9457 responses for HTTPException, custom ProblemDetailsError, and unhandled errors."},"warnings":[{"fix":"Update to >=0.4.0 and adjust clients to expect generic detail; use extensions.stack for stack trace via includeStack option.","message":"In v0.4.0, detail on 500 responses changed from raw error.message to 'An unexpected error occurred' for security. Stack trace moved to extensions.stack.","severity":"breaking","affected_versions":"<0.4.0"},{"fix":"Set autoInstance: true in problemDetailsHandler options if you want instance populated from request path.","message":"In v0.3.0, autoInstance option added but disabled by default. Existing clients expecting instance field on all responses will not see it until autoInstance is explicitly set.","severity":"breaking","affected_versions":"<0.3.0"},{"fix":"Ensure thrown ProblemDetailsError status is between 200 and 599. Invalid codes now result in 500.","message":"Status codes 1xx (100-199) are no longer allowed; handler clamps to 500. Previously passed through to Response constructor.","severity":"deprecated","affected_versions":">=0.1.4 <0.5.0"},{"fix":"Install the validator package (e.g., zod) along with hono-problem-details. Hooks are optional but will throw if missing.","message":"Validation hooks (zod, valibot) require the corresponding peer dependency installed. Missing dependency causes runtime error.","severity":"gotcha","affected_versions":">=0.2.0"},{"fix":"Ensure tsconfig has moduleResolution: 'node16' or 'bundler' for proper subpath export resolution.","message":"On Node.js, moduleResolution must be set appropriately for TypeScript types to resolve correctly (typesVersions in package.json).","severity":"gotcha","affected_versions":">=0.1.6 <0.5.0"}],"env_vars":null,"last_verified":"2026-04-25T00:00:00.000Z","next_check":"2026-07-24T00:00:00.000Z","problems":[{"fix":"Update hono-problem-details to >=0.1.6 and set tsconfig moduleResolution to 'node16' or 'bundler'.","cause":"Missing typesVersions in older versions or incorrect moduleResolution in tsconfig.","error":"Cannot find module 'hono-problem-details' or its corresponding type declarations."},{"fix":"Use import { problemDetailsHandler } from 'hono-problem-details' (ESM only).","cause":"CommonJS require used instead of ESM import.","error":"TypeError: problemDetailsHandler is not a function"},{"fix":"Use a status between 200 and 599. Invalid codes are now clamped to 500 in v0.5.0.","cause":"ProblemDetailsError status set to an out-of-range value (e.g., 0 or 1xx).","error":"RangeError: Invalid status code: 0"}],"ecosystem":"npm","meta_description":null,"install_score":null,"install_tag":null,"quickstart_score":null,"quickstart_tag":null}