Errors

May 14, 2026 · View on GitHub

Install

npm install @tryghost/errors --save

pnpm add @tryghost/errors

Purpose

Shared Ghost error classes and utilities for typed errors, context propagation, and safe stack formatting.

Usage

Ghost errors separate human-readable messages from machine-readable codes and structured metadata.

const errors = require('@tryghost/errors');

throw new errors.UnsupportedMediaTypeError({
    message: 'Zip entry exceeds maximum uncompressed size.',
    context: 'The zip contains an entry that exceeds the configured limit.',
    code: 'ENTRY_TOO_LARGE',
    errorDetails: {
        entryName,
        observedBytes,
        limitBytes,
    },
});

Field guide

Field	Purpose	Use for
`message`	Human-readable summary of what went wrong	Primary error text shown/logged by Ghost
`context`	Human-readable supporting context	A sentence or phrase that explains where/why the error happened
`code`	Machine-readable reason	UPPER_SNAKE_CASE values such as `INVALID_JWT`, `ENTRY_TOO_LARGE`, `TOKEN_EXPIRED`
`errorDetails`	Structured metadata	Objects/arrays/numbers needed for logs, Sentry extra data, debugging, or API consumers
`help`	Human-readable remediation guidance	Instructions for how to fix or recover from the error
`err`	Wrapped underlying error	Preserving details from a lower-level exception

Common mistakes

Do not put structured metadata in context. context should be a string.

// Bad
throw new errors.UnsupportedMediaTypeError({
    message: 'Zip entry exceeds maximum uncompressed size.',
    context: {
        reason: 'entry_too_large',
        observedBytes,
        limitBytes,
    },
});

// Good
throw new errors.UnsupportedMediaTypeError({
    message: 'Zip entry exceeds maximum uncompressed size.',
    context: 'The zip contains an entry that exceeds the configured limit.',
    code: 'ENTRY_TOO_LARGE',
    errorDetails: {
        observedBytes,
        limitBytes,
    },
});

Do not use lowercase strings like entry_too_large as context. Use an UPPER_SNAKE_CASE code for programmatic handling and keep context human-readable.

Develop

This is a mono repository, managed with Nx.

Follow the instructions for the top-level repo.

git clone this repo & cd into it as usual
Run pnpm install to install top-level dependencies.

Run

pnpm dev

Test

pnpm lint runs oxlint
pnpm test runs lint and tests