A small utility, used by Fastify itself, for generating consistent error objects across your codebase and plugins.
npm i @fastify/error
The module exports a function that you can use for consistent error objects, it takes 4 parameters:
createError(code, message [, statusCode [, Base [, captureStackTrace]]])code(string, required) - The error code, you can access it later witherror.code. For consistency, we recommend prefixing plugin error codes withFST_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. (egTypeError,RangeError)captureStackTrace(boolean, optional) - Whether to capture the stack trace or not.
const createError = require('@fastify/error')
const CustomError = createError('ERROR_CODE', 'Hello')
console.log(new CustomError()) // error.message => 'Hello'How to use an interpolated string:
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:
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')The module also exports createRFC9457Error, which creates error objects that can be serialized as RFC 9457 problem details objects (RFC 9457 obsoletes RFC 7807):
createRFC9457Error(code, message [, statusCode [, opts [, Base [, captureStackTrace]]]])It accepts the same parameters as createError, plus an optional opts object:
type(string, optional) - A URI reference that identifies the problem type. Defaults to'about:blank'.title(string, optional) - A short, human-readable summary of the problem type. Defaults to the HTTP status reason phrase for the error's status code (e.g.'Not Found'for404).
The created error instances expose a toProblemDetails(instance [, details]) method that returns the problem details object:
const { createRFC9457Error } = require('@fastify/error')
const QuotaExceeded = createRFC9457Error(
'QUOTA_EXCEEDED',
'Quota exceeded by %d requests',
429,
{ type: 'https://example.net/probs/quota', title: 'Quota Exceeded' }
)
console.log(new QuotaExceeded(7).toProblemDetails('/api/limits', { retryAfter: 60 }))
// {
// type: 'https://example.net/probs/quota',
// title: 'Quota Exceeded',
// status: 429,
// detail: 'Quota exceeded by 7 requests',
// instance: '/api/limits',
// code: 'QUOTA_EXCEEDED',
// details: { retryAfter: 60 }
// }instance is a URI reference that identifies the specific occurrence of the problem (e.g. the request path), and details carries additional extension members. code and details are extension members and are not defined by RFC 9457 itself.
It is possible to limit your error constructor with a generic type using TypeScript:
const CustomError = createError<[string]>('ERROR_CODE', 'Hello %s')
new CustomError('world')
//@ts-expect-error
new CustomError(1)All errors created with createError will be instances of the base error constructor you provided, or Error if none was provided.
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) // trueAll instantiated errors are instances of the FastifyError class, which can be required directly from the module.
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) // trueA FastifyError created by createError can extend another FastifyError while maintaining correct instanceof behavior.
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) // trueIf 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.
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) // trueChanging the code of an instantiated Error will not change the result of the instanceof operator.
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) // falseLicensed under MIT.