hono-problem-details

0.5.0 verified Sat Apr 25 auth: no javascript

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.

Common errors

error Cannot find module 'hono-problem-details' or its corresponding type declarations. ↓

cause Missing typesVersions in older versions or incorrect moduleResolution in tsconfig.

fix

Update hono-problem-details to >=0.1.6 and set tsconfig moduleResolution to 'node16' or 'bundler'.

error TypeError: problemDetailsHandler is not a function ↓

cause CommonJS require used instead of ESM import.

fix

Use import { problemDetailsHandler } from 'hono-problem-details' (ESM only).

error RangeError: Invalid status code: 0 ↓

cause ProblemDetailsError status set to an out-of-range value (e.g., 0 or 1xx).

fix

Use a status between 200 and 599. Invalid codes are now clamped to 500 in v0.5.0.

Warnings

breaking 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. ↓

fix Update to >=0.4.0 and adjust clients to expect generic detail; use extensions.stack for stack trace via includeStack option.

breaking 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. ↓

fix Set autoInstance: true in problemDetailsHandler options if you want instance populated from request path.

deprecated Status codes 1xx (100-199) are no longer allowed; handler clamps to 500. Previously passed through to Response constructor. ↓

fix Ensure thrown ProblemDetailsError status is between 200 and 599. Invalid codes now result in 500.

gotcha Validation hooks (zod, valibot) require the corresponding peer dependency installed. Missing dependency causes runtime error. ↓

fix Install the validator package (e.g., zod) along with hono-problem-details. Hooks are optional but will throw if missing.

gotcha On Node.js, moduleResolution must be set appropriately for TypeScript types to resolve correctly (typesVersions in package.json). ↓

fix Ensure tsconfig has moduleResolution: 'node16' or 'bundler' for proper subpath export resolution.

Install

npm install hono-problem-details

yarn add hono-problem-details

pnpm add hono-problem-details

Imports

problemDetailsHandler

wrong

const problemDetailsHandler = require('hono-problem-details')

correct

import { problemDetailsHandler } from 'hono-problem-details'

ESM-only export; CommonJS require will not work. Use named import.

ProblemDetailsError

wrong

import ProblemDetailsError from 'hono-problem-details'

correct

import { ProblemDetailsError } from 'hono-problem-details'

Named export, not default. Correct since v0.1.0.

zodProblemDetailsHook
wrong
```
import { zodProblemDetailsHook } from 'hono-problem-details'
```
correct
```
import { zodProblemDetailsHook } from 'hono-problem-details/zod'
```
Subpath export added in v0.4.0; do not import from root. Only available if zod peer dependency is installed.

ProblemDetails

wrong

import { ProblemDetails } from 'hono-problem-details'

correct

import type { ProblemDetails } from 'hono-problem-details'

Type-only import to avoid runtime issues. Available as type export.

Quickstart

Hono app with problemDetailsHandler error middleware showing RFC 9457 responses for HTTPException, custom ProblemDetailsError, and unhandled errors.

import { Hono } from 'hono';
import { HTTPException } from 'hono/http-exception';
import { problemDetailsHandler, ProblemDetailsError } from 'hono-problem-details';

const app = new Hono();

app.onError(problemDetailsHandler({ autoInstance: true }));

app.get('/ok', (c) => c.text('OK'));

app.get('/not-found', (c) => {
  throw new HTTPException(404, { message: 'Resource not found' });
});

app.get('/custom', (c) => {
  throw new ProblemDetailsError({
    status: 422,
    title: 'Validation Failed',
    detail: 'The request body is not valid.',
    extensions: { errors: [{ field: 'username', message: 'required' }] },
  });
});

app.get('/error', (c) => {
  throw new Error('Something went wrong');
});

export default app;