# whoops

> Create and throw named, qualified Error subclasses with a small factory API.

Latest version **5.1.4** (published 2026-08-03) · MIT license · 0 weekly downloads

## Install

```sh
npm install whoops
pnpm add whoops
yarn add whoops
bun add whoops
```

## Health

**Score 63/100 (C)** — status: active.

Positive: has types package; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; no esm support.

## Facts

| | |
|---|---|
| Version | 5.1.4 |
| Published | 2026-08-03 |
| First published | 2015-11-20 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | separate (@types/whoops) |
| Module format | CommonJS |
| Node | >= 8 |
| Dependencies | 0 |
| Unpacked size | 9.8 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Author | Kiko Beats |
| Maintainers | kikobeats |
| Keywords | class, constructor, custom, error, exception, factory, named, qualified, throw, whoops |

## Links

- npm: https://www.npmjs.com/package/whoops
- Repository: https://github.com/kikobeats/whoops
- Homepage: https://github.com/Kikobeats/whoops
- Issues: https://github.com/Kikobeats/whoops/issues
- npm.io page: https://npm.io/package/whoops

## 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

- 5.1.4 (latest) — 2026-08-03
- 5.1.3 — 2026-07-30
- 5.1.2 — 2026-04-14
- 5.1.1 — 2026-03-18
- 5.1.0 — 2026-01-22
- 5.0.7 — 2025-12-29
- 5.0.6 — 2025-12-29
- 5.0.5 — 2025-11-21
- 5.0.4 — 2025-10-15
- 5.0.3 — 2025-09-06
- 5.0.2 — 2025-08-12
- 5.0.1 — 2025-01-28
- 5.0.0 — 2025-01-28
- 4.1.8 — 2025-01-27
- 4.1.7 — 2023-10-29
- … 24 more at https://npm.io/package/whoops/versions

## README

# whoops

![Last version](https://img.shields.io/github/tag/Kikobeats/whoops.svg?style=flat-square)
[![Coverage Status](https://img.shields.io/coveralls/Kikobeats/whoops.svg?style=flat-square)](https://coveralls.io/github/Kikobeats/whoops)
[![NPM Status](http://img.shields.io/npm/dm/whoops.svg?style=flat-square)](https://www.npmjs.org/package/whoops)

> It makes simple throw qualified errors. Inspired in [errno](https://github.com/rvagg/node-errno), [create-error-class](https://github.com/floatdrop/create-error-class) and [fault](https://github.com/wooorm/fault).

## Why

- 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.
- Less than 50 lines (~500 bytes)

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

## Install

```bash
npm install whoops --save
```

Basically it turns:

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

Into a one line more productive declaration:

```js
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:

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

Create domain specific errors providing a `className` as first argument:

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

The qualified error will be extends from `Error`:

```js
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:

```js
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:

```js
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](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Error)          | whoops           |
| [TypeError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/TypeError)      | whoops.type      |
| [RangeError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/RangeError)     | whoops.range     |
| [EvalError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/EvalError)      | whoops.eval      |
| [SyntaxError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/SyntaxError)    | whoops.syntax    |
| [ReferenceError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/ReferenceError) | whoops.reference |
| [URIError](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/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:

```js
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:

```js
switch (err.name) {
  case 'JSONError':
    console.log('your error logic here')
    break
  default:
    console.log('undefined code')
    break
};
```

## Related

- [create-error-class](https://github.com/floatdrop/create-error-class) – Create error class.
- [fault](https://github.com/wooorm/fault) – Functional errors with formatted output.


## License

MIT © [Kiko Beats](http://www.kikobeats.com)

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