It makes simple create qualified errors.
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


Last version Build Status Coverage Status Dependency status Dev Dependencies Status NPM Status Donate

It makes simple throw qualified errors. Inspired in errno, create-error-class and fault.


  • An easy way to create qualified errors.
  • Using the standard Error interface in browser and NodeJS.
  • Attach extra information, being flexible with whatever user case.

This library is a compromise to provide a clean API for use Error native class.


npm install whoops --save

Basically it turns:

const error = Error('Something is wrong') = 'DAMNError'
throw error // => 'DAMNError: ENOFILE, Something is wrong'

Into a one line more productive declaration:

const whoops = require('whoops')
const userError = whoops('UserError')

throw userError('User not found') // => 'UserError: User not found'

Creating Qualified Errors

Call whoops to get a constructor function. Every time you call the constructor, you get an Error instance:

const whoops = require('whoops')
const myError = whoops()
throw myError()

Create domain specific errors providing a className as first argument:

const whoops = require('whoops')
const userError = whoops('userError')
throw userError()

The qualified error will be extends from Error:

const whoops = require('whoops')
const userError = whoops('userError')
const error = userError()
console.log(error instanceof Error); // => true

Attach extra information passing a props as second argument:

const whoops = require('whoops')
const userError = whoops('userError', {code: 'ENOVALID'})
const err = userError()
console.log(`My error code is ${err.code}`) // => My error code is ENOVALID

You can associate dynamic props as well:

const whoops = require('whoops')
const userError = whoops('userError', {
  code: 'ENOVALID',
  message: props => `User '${props.username}' not found`

const err = userError({username: 'kiko'})
console.log(err.message) // => User 'kiko' not found

Error Types

By default you will get Error instances calling whoops, but you can get different errors calling the properly method:

Name Method
Error whoops
TypeError whoops.type
RangeError whoops.range
EvalError whoops.eval
SyntaxError whoops.syntax
ReferenceError whoops.reference
URIError whoops.uri

Extra: Always throw/return an Error!

If you code implementation is

  • synchronous, throws Error. If you just return the Error nothings happens!.
  • asynchronous, returns Error in the first argument of the callback (or using promises).

About asynchronous code, is correct return a Object that is not a Error in the first argument of the callback to express unexpected behavior, but the Object doesn't have a type and definitely can't follow a error interface for determinate a special behavior:

callback('LOL something was wrong') // poor
callback({message: 'LOL something was wrong' } // poor, but better
callback(whoops('LOL, something was wrong') // BEST!

Passing always an Error you can can associated different type of error with different behavior:

switch ( {
  case 'JSONError':
    console.log('your error logic here')
    console.log('undefined code')


MIT © Kiko Beats