Installation:

npm: npm install @hapi/boom

yarn: yarn add @hapi/boom

boom provides a set of utilities for returning HTTP errors. Each utility returns a Boom error response object which includes the following properties:

  • isBoom - if true, indicates this is a Boom object instance. Note that this boolean should only be used if the error is an instance of Error. If it is not certain, use Boom.isBoom() instead.
  • isServer - convenience bool indicating status code >= 500.
  • message - the error message.
  • typeof - the constructor used to create the error (e.g. Boom.badRequest).
  • output - the formatted response. Can be directly manipulated after object construction to return a custom error response. Allowed root keys:
    • statusCode - the HTTP status code (typically 4xx or 5xx).
    • headers - an object containing any HTTP headers where each key is a header name and value is the header content.
    • payload - the formatted object used as the response payload (stringified). Can be directly manipulated but any changes will be lost if reformat() is called. Any content allowed and by default includes the following content:
      • statusCode - the HTTP status code, derived from error.output.statusCode.
      • error - the HTTP status message (e.g. 'Bad Request', 'Internal Server Error') derived from statusCode.
      • message - the error message derived from error.message.
  • inherited Error properties.

The Boom object also supports the following method:

reformat(debug)

Rebuilds error.output using the other object properties where:

  • debug - a Boolean that, when true, causes Internal Server Error messages to be left in tact. Defaults to false, meaning that Internal Server Error messages are redacted.

Note that Boom object will return true when used with instanceof Boom, but do not use the Boom prototype (they are either plain Error or the error prototype passed in). This means Boom objects should only be tested using instanceof Boom or Boom.isBoom() but not by looking at the prototype or contructor information. This limitation is to avoid manipulating the prototype chain which is very slow.

Helper Methods

new Boom(message, [options])

Creates a new Boom object using the provided message and then calling boomify() to decorate the error with the Boom properties, where:

  • message - the error message. If message is an error, it is the same as calling boomify() directly.
  • options - and optional object where:
    • statusCode - the HTTP status code. Defaults to 500 if no status code is already set.
    • data - additional error information (assigned to error.data).
    • decorate - an option with extra properties to set on the error object.
    • ctor - constructor reference used to crop the exception call stack output.
    • if message is an error object, also supports the other boomify() options.
boomify(err, [options])

Decorates an error with the Boom properties where:

  • err - the Error object to decorate.
  • options - optional object with the following optional settings:
    • statusCode - the HTTP status code. Defaults to 500 if no status code is already set and err is not a Boom object.
    • message - error message string. If the error already has a message, the provided message is added as a prefix. Defaults to no message.
    • decorate - an option with extra properties to set on the error object.
    • override - if false, the err provided is a Boom object, and a statusCode or message are provided, the values are ignored. Defaults to true (apply the provided statusCode and message options to the error regardless of its type, Error or Boom object).
var error = new Error('Unexpected input');
Boom.boomify(error, { statusCode: 400 });
isBoom(err)

Identifies whether an error is a Boom object. Same as calling instanceof Boom.

HTTP 4xx Errors

Boom.badRequest([message], [data])

Returns a 400 Bad Request error where:

  • message - optional message.
  • data - optional additional error data.
Boom.badRequest('invalid query');

Generates the following response payload:

{
    "statusCode": 400,
    "error": "Bad Request",
    "message": "invalid query"
}
Boom.unauthorized([message], [scheme], [attributes])

Returns a 401 Unauthorized error where:

  • message - optional message.
  • scheme can be one of the following:
    • an authentication scheme name
    • an array of string values. These values will be separated by ', ' and set to the 'WWW-Authenticate' header.
  • attributes - an object of values to use while setting the 'WWW-Authenticate' header. This value is only used when scheme is a string, otherwise it is ignored. Every key/value pair will be included in the 'WWW-Authenticate' in the format of 'key="value"' as well as in the response payload under the attributes key. Alternatively value can be a string which is use to set the value of the scheme, for example setting the token value for negotiate header. If string is used message parameter must be null. null and undefined will be replaced with an empty string. If attributes is set, message will be used as the 'error' segment of the 'WWW-Authenticate' header. If message is unset, the 'error' segment of the header will not be present and isMissing will be true on the error object.

If either scheme or attributes are set, the resultant Boom object will have the 'WWW-Authenticate' header set for the response.

Boom.unauthorized('invalid password');

Generates the following response:

"payload": {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "invalid password"
},
"headers" {}
Boom.unauthorized('invalid password', 'sample');

Generates the following response:

"payload": {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "invalid password",
    "attributes": {
        "error": "invalid password"
    }
},
"headers" {
  "WWW-Authenticate": "sample error=\"invalid password\""
}
Boom.unauthorized(null, 'Negotiate', 'VGhpcyBpcyBhIHRlc3QgdG9rZW4=');

Generates the following response:

"payload": {
    "statusCode": 401,
    "error": "Unauthorized",
    "attributes": "VGhpcyBpcyBhIHRlc3QgdG9rZW4="
},
"headers" {
  "WWW-Authenticate": "Negotiate VGhpcyBpcyBhIHRlc3QgdG9rZW4="
}
Boom.unauthorized('invalid password', 'sample', { ttl: 0, cache: null, foo: 'bar' });

Generates the following response:

"payload": {
    "statusCode": 401,
    "error": "Unauthorized",
    "message": "invalid password",
    "attributes": {
        "error": "invalid password",
        "ttl": 0,
        "cache": "",
        "foo": "bar"
    }
},
"headers" {
  "WWW-Authenticate": "sample ttl=\"0\", cache=\"\", foo=\"bar\", error=\"invalid password\""
}
Boom.paymentRequired([message], [data])

Returns a 402 Payment Required error where:

  • message - optional message.
  • data - optional additional error data.
Boom.paymentRequired('bandwidth used');

Generates the following response payload:

{
    "statusCode": 402,
    "error": "Payment Required",
    "message": "bandwidth used"
}
Boom.forbidden([message], [data])

Returns a 403 Forbidden error where:

  • message - optional message.
  • data - optional additional error data.
Boom.forbidden('try again some time');

Generates the following response payload:

{
    "statusCode": 403,
    "error": "Forbidden",
    "message": "try again some time"
}
Boom.notFound([message], [data])

Returns a 404 Not Found error where:

  • message - optional message.
  • data - optional additional error data.
Boom.notFound('missing');

Generates the following response payload:

{
    "statusCode": 404,
    "error": "Not Found",
    "message": "missing"
}
Boom.methodNotAllowed([message], [data], [allow])

Returns a 405 Method Not Allowed error where:

  • message - optional message.
  • data - optional additional error data.
  • allow - optional string or array of strings (to be combined and separated by ', ') which is set to the 'Allow' header.
Boom.methodNotAllowed('that method is not allowed');

Generates the following response payload:

{
    "statusCode": 405,
    "error": "Method Not Allowed",
    "message": "that method is not allowed"
}
Boom.notAcceptable([message], [data])

Returns a 406 Not Acceptable error where:

  • message - optional message.
  • data - optional additional error data.
Boom.notAcceptable('unacceptable');

Generates the following response payload:

{
    "statusCode": 406,
    "error": "Not Acceptable",
    "message": "unacceptable"
}
Boom.proxyAuthRequired([message], [data])

Returns a 407 Proxy Authentication Required error where:

  • message - optional message.
  • data - optional additional error data.
Boom.proxyAuthRequired('auth missing');

Generates the following response payload:

{
    "statusCode": 407,
    "error": "Proxy Authentication Required",
    "message": "auth missing"
}
Boom.clientTimeout([message], [data])

Returns a 408 Request Time-out error where:

  • message - optional message.
  • data - optional additional error data.
Boom.clientTimeout('timed out');

Generates the following response payload:

{
    "statusCode": 408,
    "error": "Request Time-out",
    "message": "timed out"
}
Boom.conflict([message], [data])

Returns a 409 Conflict error where:

  • message - optional message.
  • data - optional additional error data.
Boom.conflict('there was a conflict');

Generates the following response payload:

{
    "statusCode": 409,
    "error": "Conflict",
    "message": "there was a conflict"
}
Boom.resourceGone([message], [data])

Returns a 410 Gone error where:

  • message - optional message.
  • data - optional additional error data.
Boom.resourceGone('it is gone');

Generates the following response payload:

{
    "statusCode": 410,
    "error": "Gone",
    "message": "it is gone"
}
Boom.lengthRequired([message], [data])

Returns a 411 Length Required error where:

  • message - optional message.
  • data - optional additional error data.
Boom.lengthRequired('length needed');

Generates the following response payload:

{
    "statusCode": 411,
    "error": "Length Required",
    "message": "length needed"
}
Boom.preconditionFailed([message], [data])

Returns a 412 Precondition Failed error where:

  • message - optional message.
  • data - optional additional error data.
Boom.preconditionFailed();

Generates the following response payload:

{
    "statusCode": 412,
    "error": "Precondition Failed"
}
Boom.entityTooLarge([message], [data])

Returns a 413 Request Entity Too Large error where:

  • message - optional message.
  • data - optional additional error data.
Boom.entityTooLarge('too big');

Generates the following response payload:

{
    "statusCode": 413,
    "error": "Request Entity Too Large",
    "message": "too big"
}
Boom.uriTooLong([message], [data])

Returns a 414 Request-URI Too Large error where:

  • message - optional message.
  • data - optional additional error data.
Boom.uriTooLong('uri is too long');

Generates the following response payload:

{
    "statusCode": 414,
    "error": "Request-URI Too Large",
    "message": "uri is too long"
}
Boom.unsupportedMediaType([message], [data])

Returns a 415 Unsupported Media Type error where:

  • message - optional message.
  • data - optional additional error data.
Boom.unsupportedMediaType('that media is not supported');

Generates the following response payload:

{
    "statusCode": 415,
    "error": "Unsupported Media Type",
    "message": "that media is not supported"
}
Boom.rangeNotSatisfiable([message], [data])

Returns a 416 Requested Range Not Satisfiable error where:

  • message - optional message.
  • data - optional additional error data.
Boom.rangeNotSatisfiable();

Generates the following response payload:

{
    "statusCode": 416,
    "error": "Requested Range Not Satisfiable"
}
Boom.expectationFailed([message], [data])

Returns a 417 Expectation Failed error where:

  • message - optional message.
  • data - optional additional error data.
Boom.expectationFailed('expected this to work');

Generates the following response payload:

{
    "statusCode": 417,
    "error": "Expectation Failed",
    "message": "expected this to work"
}
Boom.teapot([message], [data])

Returns a 418 I'm a Teapot error where:

  • message - optional message.
  • data - optional additional error data.
Boom.teapot('sorry, no coffee...');

Generates the following response payload:

{
    "statusCode": 418,
    "error": "I'm a Teapot",
    "message": "Sorry, no coffee..."
}
Boom.badData([message], [data])

Returns a 422 Unprocessable Entity error where:

  • message - optional message.
  • data - optional additional error data.
Boom.badData('your data is bad and you should feel bad');

Generates the following response payload:

{
    "statusCode": 422,
    "error": "Unprocessable Entity",
    "message": "your data is bad and you should feel bad"
}
Boom.locked([message], [data])

Returns a 423 Locked error where:

  • message - optional message.
  • data - optional additional error data.
Boom.locked('this resource has been locked');

Generates the following response payload:

{
    "statusCode": 423,
    "error": "Locked",
    "message": "this resource has been locked"
}
Boom.failedDependency([message], [data])

Returns a 424 Failed Dependency error where:

  • message - optional message.
  • data - optional additional error data.
Boom.failedDependency('an external resource failed');

Generates the following response payload:

{
    "statusCode": 424,
    "error": "Failed Dependency",
    "message": "an external resource failed"
}
Boom.preconditionRequired([message], [data])

Returns a 428 Precondition Required error where:

  • message - optional message.
  • data - optional additional error data.
Boom.preconditionRequired('you must supply an If-Match header');

Generates the following response payload:

{
    "statusCode": 428,
    "error": "Precondition Required",
    "message": "you must supply an If-Match header"
}
Boom.tooManyRequests([message], [data])

Returns a 429 Too Many Requests error where:

  • message - optional message.
  • data - optional additional error data.
Boom.tooManyRequests('you have exceeded your request limit');

Generates the following response payload:

{
    "statusCode": 429,
    "error": "Too Many Requests",
    "message": "you have exceeded your request limit"
}
Boom.illegal([message], [data])

Returns a 451 Unavailable For Legal Reasons error where:

  • message - optional message.
  • data - optional additional error data.
Boom.illegal('you are not permitted to view this resource for legal reasons');

Generates the following response payload:

{
    "statusCode": 451,
    "error": "Unavailable For Legal Reasons",
    "message": "you are not permitted to view this resource for legal reasons"
}

HTTP 5xx Errors

All 500 errors hide your message from the end user. Your message is recorded in the server log.

Boom.badImplementation([message], [data]) - (alias: internal)

Returns a 500 Internal Server Error error where:

  • message - optional message.
  • data - optional additional error data.
Boom.badImplementation('terrible implementation');

Generates the following response payload:

{
    "statusCode": 500,
    "error": "Internal Server Error",
    "message": "An internal server error occurred"
}
Boom.notImplemented([message], [data])

Returns a 501 Not Implemented error where:

  • message - optional message.
  • data - optional additional error data.
Boom.notImplemented('method not implemented');

Generates the following response payload:

{
    "statusCode": 501,
    "error": "Not Implemented",
    "message": "method not implemented"
}
Boom.badGateway([message], [data])

Returns a 502 Bad Gateway error where:

  • message - optional message.
  • data - optional additional error data.
Boom.badGateway('that is a bad gateway');

Generates the following response payload:

{
    "statusCode": 502,
    "error": "Bad Gateway",
    "message": "that is a bad gateway"
}
Boom.serverUnavailable([message], [data])

Returns a 503 Service Unavailable error where:

  • message - optional message.
  • data - optional additional error data.
Boom.serverUnavailable('unavailable');

Generates the following response payload:

{
    "statusCode": 503,
    "error": "Service Unavailable",
    "message": "unavailable"
}
Boom.gatewayTimeout([message], [data])

Returns a 504 Gateway Time-out error where:

  • message - optional message.
  • data - optional additional error data.
Boom.gatewayTimeout();

Generates the following response payload:

{
    "statusCode": 504,
    "error": "Gateway Time-out"
}

F.A.Q.

Q How do I include extra information in my responses? output.payload is missing data, what gives?

A There is a reason the values passed back in the response payloads are pretty locked down. It's mostly for security and to not leak any important information back to the client. This means you will need to put in a little more effort to include extra information about your custom error. Check out the "Error transformation" section in the hapi documentation.

Changelog

8.0.1
breaking changes
#253
change new Boom() to new Boom.Boom()
#252
Drop support for node 8
#251
Add types
#246
boom doesn't consider message not set directly on error object when deciding whether it is a compatible error
#248
Error TS2709: Cannot use namespace 'Boom' as a type.
#245
Fix default export. Fixes #244.
#244
Typescript - can't extend Boom
#243
Improve types
#242
Typescript definitions missing internal()
#241
Ts fix
#240
Fix types: Update static isBoom to be a type guard.
#239
Missing error properties
#238
Fix types: serviceUnavailable -> serverUnavailable.
#237
Types have typo: serverUnavailable -> serviceUnavailable
7.4.5
breaking changes
#216
Handle case of message property with getter-only
#215
`typeof` and `reformat` should not be enumerable
#233
Added TS declarations
#229
Update deps
#221
Update deps
#220
Fix dependency
#219
Change module namespace
#211
add debug mode to reformat()
#208
Remove engines
#206
Update hoek v6
#188
424 Failed dependency implementation
7.1.1
breaking changes
#173
Support instanceof
#172
Add decorate option
7.0.0
breaking changes
#171
Remove wrap() and create()
6.0.0
breaking changes
#165
Node v8
#218
Load the commercial version of hoek
#217
Commercial version of v5 branch
#160
Allow decorating a boom error
#157
Hide message on 500 when error is provided as data
#156
Added typeOf functionality
5.0.0
breaking changes
#154
Boom.wrap with a provided message doesn't format the payload
#152
Boom.badGateway( string, Boom.anything() )
#149
fix #148 when Boom supplied to wrapper
#148
Remove line from wrap function
#147
Unauthorized extension for #146
#146
Unauthorized
#142
Boom.wrap never sends custom message to client
#139
Adds support for `Boom.someMethod(err)`, closes #138
#138
Preservation of `err.name` via `Boom.create` or `Boom[someMethod]`
#78
Add Boom.teapot() method with documentation and tests
#133
Add 'allow' parameter to methodNotAllowed for setting 'Allow' header
#132
405 Method Not Allowed should provide an argument for specifying "Allow" header
#130
Add 402 payment required
#129
Add Boom.internal() to API docs fixes #127
4.0.0
breaking changes
#125
Remove deprecated serverTimeout
#118
Remove serverTimeout()
#121
Added .npmignore file.
#119
Rename serverTimeout to serverUnavailable
#117
serverTimeout() should be aliased to serverUnavailable()
#108
Create .npmignore
#113
Updated to code 3.
#112
Added HTTP code 423 Locked
#111
HTTP Error 423 (Locked)
#110
Added node 6.
#97
Use quotes instead of backticks
#95
Changed prototype logic.
#94
Cleanup for 254593fd1d09e79049692675a4f9b7b5108b36d8
#93
Document Illegal
#92
Status Code Hash
#91
Add new 451 Unavailable For Legal Reasons
3.0.0
breaking changes
#83
es6 style. Closes #77
#77
Node 4 Updates
#81
Upgrade to lab 7.x.x
#80
Fix ctor passing in serverError helper
#79
Stack trace filtering not working for serverError constructors
#75
Support Precondition Required
#74
Precondition required is not supported
#68
Call captureStackTrace to filter boom from traces
#67
Use captureStackTrace to remove boom artifacts from stack traces
#63
Unauthorized
#62
Expose unauthorized attributes in payload
#60
Style Cleanup
#59
Update license attribute
#52
Coerse statusCode to an Integer
#51
Make sure Boom initialize method auto cast string statusCode to Integer if possible
#45
Added isServer
#41
Easy way to determine if the client or server is at fault
#40
Lab 5.0, code 1.0
#33
Added status code 429 Too Many Requests.
#27
Update to lab 4.x.x. Bumped version.
#26
Rename spumko to hapijs
#25
Add a 422 badData method
#23
Default message to http status
#22
Upgrade dependencies
#21
Allow every helper to set data property
#20
Internal errors (500) should never expose err.message
#19
Bring coverage back to 100% after lab fix
#17
Don't override data if user error already have a data attribute
clipboard