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
muslnode 18–226 runs
build_error
glibcnode 18–226 runs
build_error
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
ProblemDocument
✓ import { ProblemDocument } from 'http-problem-details';
✗ const ProblemDocument = require('http-problem-details').ProblemDocument;
For ESM modules, use named imports. CommonJS `require` syntax is shown in older README examples but ESM is preferred in modern Node.js/TypeScript setups.
ProblemDocumentExtension
✓ import { ProblemDocumentExtension } from 'http-problem-details';
✗ const ProblemDocumentExtension = require('http-problem-details').ProblemDocumentExtension;
Use named imports for ESM. Older CJS `require` examples exist, but modern usage favors ESM. This class is for adding custom key-value pairs to the problem document.
ProblemDocument and ProblemDocumentExtension (CommonJS)
✓ const { ProblemDocument, ProblemDocumentExtension } = require('http-problem-details');
✗ const ProblemDocument = require('http-problem-details'); // Incorrect destructuring
If using CommonJS, destructure the named exports from the `require` call. Directly requiring the package without destructuring will not work as expected.
This quickstart demonstrates how to integrate `http-problem-details` within an Express.js error handling middleware to generate RFC 7807 compliant error responses, including custom extension members.
import { ProblemDocument, ProblemDocumentExtension } from 'http-problem-details';
import { Request, Response } from 'express';
// Example of an Express error handler generating a Problem Document
export const errorHandler = (err: any, req: Request, res: Response, next: Function) => {
console.error(err);
let problemDocument: ProblemDocument;
// Handle a specific custom error, e.g., 'InsufficientFundsError'
if (err.name === 'InsufficientFundsError') {
const extension = new ProblemDocumentExtension({
balance: err.currentBalance, // assuming err has currentBalance property
required: err.amountRequired,
transactions: ['/account/123/tx/456', '/account/123/tx/789']
});
problemDocument = new ProblemDocument({
type: 'https://example.com/probs/out-of-credit',
title: 'You do not have enough credit.',
detail: err.message || 'Your current balance is insufficient for this operation.',
status: 403, // Forbidden
instance: req.originalUrl // Reflects the specific request
}, extension);
} else if (err.status) {
// Handle errors that already have an HTTP status
problemDocument = new ProblemDocument({
type: 'about:blank',
title: err.message || 'An unexpected error occurred.',
status: err.status,
detail: err.detail,
instance: req.originalUrl
});
} else {
// Default catch-all for unknown errors
problemDocument = new ProblemDocument({
type: 'about:blank',
title: 'Internal Server Error',
status: 500,
detail: 'An unexpected server error occurred.',
instance: req.originalUrl
});
}
res.status(problemDocument.status || 500).json(problemDocument);
};
// To demonstrate usage:
// class InsufficientFundsError extends Error {
// constructor(message: string, public currentBalance: number, public amountRequired: number) {
// super(message);
// this.name = 'InsufficientFundsError';
// }
// }
//
// const mockReq: Request = { originalUrl: '/api/checkout/item/123' } as Request;
// const mockRes: Response = { status: jest.fn().mockReturnThis(), json: jest.fn() } as unknown as Response;
// const mockNext = jest.fn();
//
// const error = new InsufficientFundsError('Not enough funds to purchase item.', 30, 50);
// errorHandler(error, mockReq, mockRes, mockNext);
//
// console.log(mockRes.json.mock.calls[0][0]);
Errors
Common errors & fixes
Error: Invalid URI provided for 'type'
The `type` property passed to the ProblemDocument constructor was not a valid URI string.
fixEnsure the `type` property is a well-formed URI, such as 'https://example.com/errors/bad-request' or 'about:blank'.
Error: Invalid URI provided for 'instance'
The `instance` property passed to the ProblemDocument constructor was not a valid URI string.
fixProvide a valid URI for `instance`, typically a path or URL pointing to the specific occurrence of the problem, e.g., '/orders/12345/items/failed'.
TypeError: ProblemDocument is not a constructor
Attempting to use `require('http-problem-details')` directly as a constructor, or not correctly destructuring named exports in CommonJS.
fixFor CommonJS, use `const { ProblemDocument } = require('http-problem-details');`. For ESM, use `import { ProblemDocument } from 'http-problem-details';`. Audit
Dependencies
No dependency data recorded yet.