# @fastify/error

> A small utility, used by Fastify itself, for generating consistent error objects across your codebase and plugins.

Latest version **4.2.0** (published 2025-06-01) · MIT license · 0 weekly downloads

## Install

```sh
npm install @fastify/error
pnpm add @fastify/error
yarn add @fastify/error
bun add @fastify/error
```

## Health

**Score 45/100 (D)** — status: stable.

Positive: has types; no vulnerabilities; high quality score.

Warnings: low downloads; no esm support.

Negative: stale.

## Facts

| | |
|---|---|
| Version | 4.2.0 |
| Published | 2025-06-01 |
| First published | 2022-04-27 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | CommonJS |
| Dependencies | 0 |
| Unpacked size | 36 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 135 |
| Author | Tomas Della Vedova |
| Maintainers | starptech, simoneb, coopflow, delvedor, matteo.collina, allevo, jsumners, zekth, rafaelgss, eomm, fox1t, airhorns, kibertoad, climba03003, galvez, simenb, gurgunday, metcoder95, ivan-tymoshenko, fdawgs |
| Keywords | fastify, error, utility, plugin |

## Links

- npm: https://www.npmjs.com/package/@fastify/error
- Repository: https://github.com/fastify/fastify-error
- Homepage: https://github.com/fastify/fastify-error#readme
- Issues: https://github.com/fastify/fastify-error/issues
- Funding: https://github.com/sponsors/fastify
- npm.io page: https://npm.io/package/@fastify/error

## Alternatives

- [@sentry/react-native](https://npm.io/package/@sentry/react-native.md) — 2.6M weekly downloads
- [@ardatan/aggregate-error](https://npm.io/package/@ardatan/aggregate-error.md) — 708.1K weekly downloads
- [custom-error-generator](https://npm.io/package/custom-error-generator.md) — 2.0K weekly downloads
- [@technik-sde/prosemirror-recreate-transform](https://npm.io/package/@technik-sde/prosemirror-recreate-transform.md) — 1.5K weekly downloads
- [@suchipi/error-utils](https://npm.io/package/@suchipi/error-utils.md) — 78 weekly downloads

## Recent versions

- 4.2.0 (latest) — 2025-06-01
- 4.1.0 — 2025-03-12
- 4.0.0 — 2024-06-21
- 3.4.1 — 2023-11-04
- 3.4.0 — 2023-10-03
- 3.3.0 — 2023-06-23
- 3.2.1 — 2023-06-03
- 3.2.0 — 2022-12-07
- 3.1.0 — 2022-12-02
- 3.0.0 — 2022-05-23
- 2.0.0 — 2022-04-27

## README

# @fastify/error

[![CI](https://github.com/fastify/fastify-error/actions/workflows/ci.yml/badge.svg?branch=main)](https://github.com/fastify/fastify-error/actions/workflows/ci.yml)
[![NPM version](https://img.shields.io/npm/v/@fastify/error.svg?style=flat)](https://www.npmjs.com/package/@fastify/error)
[![neostandard javascript style](https://img.shields.io/badge/code_style-neostandard-brightgreen?style=flat)](https://github.com/neostandard/neostandard)

A small utility, used by Fastify itself, for generating consistent error objects across your codebase and plugins.

### Install
```
npm i @fastify/error
```

### Usage

The module exports a function that you can use for consistent error objects, it takes 4 parameters:

```js
createError(code, message [, statusCode [, Base [, captureStackTrace]]])
```

- `code` (`string`, required) - The error code, you can access it later with `error.code`. For consistency, we recommend prefixing plugin error codes with `FST_`
- `message` (`string`, required) - The error message. You can also use interpolated strings for formatting the message.
- `statusCode` (`number`, optional) - The status code that Fastify will use if the error is sent via HTTP.
- `Base` (`ErrorConstructor`, optional) - The base error object that will be used. (eg `TypeError`, `RangeError`)
- `captureStackTrace` (`boolean`, optional) - Whether to capture the stack trace or not.

```js
const createError = require('@fastify/error')
const CustomError = createError('ERROR_CODE', 'Hello')
console.log(new CustomError()) // error.message => 'Hello'
```

How to use an interpolated string:
```js
const createError = require('@fastify/error')
const CustomError = createError('ERROR_CODE', 'Hello %s')
console.log(new CustomError('world')) // error.message => 'Hello world'
```

How to add cause:
```js
const createError = require('@fastify/error')
const CustomError = createError('ERROR_CODE', 'Hello %s')
console.log(new CustomError('world', {cause: new Error('cause')}))
// error.message => 'Hello world'
// error.cause => Error('cause')
```

### TypeScript

It is possible to limit your error constructor with a generic type using TypeScript:

```ts
const CustomError = createError<[string]>('ERROR_CODE', 'Hello %s')
new CustomError('world')
//@ts-expect-error
new CustomError(1)
```

### instanceof

All errors created with `createError` will be instances of the base error constructor you provided, or `Error` if none was provided.

```js
const createError = require('@fastify/error')
const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
const customError = new CustomError('world')

console.log(customError instanceof CustomError) // true
console.log(customError instanceof TypeError) // true
console.log(customError instanceof Error) // true
```

All instantiated errors are instances of the `FastifyError` class, which can be required directly from the module.

```js
const { createError, FastifyError } = require('@fastify/error')
const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
const customError = new CustomError('world')

console.log(customError instanceof FastifyError) // true
```

A `FastifyError` created by `createError` can extend another `FastifyError` while maintaining correct `instanceof` behavior.

```js
const { createError, FastifyError } = require('@fastify/error')

const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
const ChildCustomError = createError('CHILD_ERROR_CODE', 'Hello %s', 500, CustomError)

const customError = new ChildCustomError('world')

console.log(customError instanceof ChildCustomError) // true
console.log(customError instanceof CustomError) // true
console.log(customError instanceof FastifyError) // true
console.log(customError instanceof TypeError) // true
console.log(customError instanceof Error) // true
```

If `fastify-error` is installed multiple times directly or as a transitive dependency, `instanceof` checks for errors created by `createError` will still work correctly across these installations, as long as their error codes (e.g., `FST_ERR_CUSTOM_ERROR`) are identical.

```js
const { createError, FastifyError } = require('@fastify/error')

// CustomError from `@fastify/some-plugin` is created with `createError` and
// has its own `@fastify/error` installation as dependency. CustomError has
// FST_ERR_CUSTOM_ERROR as code.
const { CustomError: CustomErrorFromPlugin } = require('@fastify/some-plugin')

const CustomError = createError('FST_ERR_CUSTOM_ERROR', 'Hello %s', 500)

const customError = new CustomError('world')
const customErrorFromPlugin = new CustomErrorFromPlugin('world')

console.log(customError instanceof CustomError) // true
console.log(customError instanceof CustomErrorFromPlugin) // true
console.log(customErrorFromPlugin instanceof CustomError) // true
console.log(customErrorFromPlugin instanceof CustomErrorFromPlugin) // true
```

Changing the code of an instantiated Error will not change the result of the `instanceof` operator.

```js
const { createError, FastifyError } = require('@fastify/error')

const CustomError = createError('ERROR_CODE', 'Hello %s', 500, TypeError)
const AnotherCustomError = createError('ANOTHER_ERROR_CODE', 'Hello %s', 500, CustomError)

const customError = new CustomError('world')
customError.code = 'ANOTHER_ERROR_CODE'

console.log(customError instanceof CustomError) // true
console.log(customError instanceof AnotherCustomError) // false
```

## License

Licensed under [MIT](./LICENSE).

---
_Source: https://npm.io/package/@fastify/error · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._