# yerror

> It helps to know why you got an error.

Latest version **11.0.0** (published 2026-04-07) · MIT license · 0 weekly downloads

## Install

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

## Health

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

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

Warnings: low downloads.

## Facts

| | |
|---|---|
| Version | 11.0.0 |
| Published | 2026-04-07 |
| First published | 2015-02-25 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=24.14.0 |
| Dependencies | 0 |
| Unpacked size | 65.5 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| GitHub stars | 12 |
| Author | Nicolas Froidure |
| Maintainers | xavhan, nfroidure, gplancke, arnaudspanneut, sebastienelet |
| Keywords | error, why, better |

## Links

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

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

- 11.0.0 (latest) — 2026-04-07
- 9.1.1 — 2026-03-30
- 9.1.0 — 2026-03-28
- 9.0.0 — 2026-03-25
- 8.0.0 — 2023-08-12
- 7.0.0 — 2023-08-11
- 6.2.1 — 2022-12-19
- 6.2.0 — 2022-12-19
- 6.1.1 — 2022-05-27
- 6.1.0 — 2022-05-27
- 6.0.2 — 2022-05-25
- 6.0.1 — 2021-04-10
- 6.0.0 — 2021-04-09
- 5.0.0 — 2019-12-10
- 4.0.1 — 2019-02-02
- … 11 more at https://npm.io/package/yerror/versions

## README

[//]: # ( )
[//]: # (This file is automatically generated by a `metapak`)
[//]: # (module. Do not change it  except between the)
[//]: # (`content:start/end` flags, your changes would)
[//]: # (be overridden.)
[//]: # ( )
# yerror
> It helps to know why you got an error.

[![GitHub license](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/nfroidure/yerror/blob/main/LICENSE)


[//]: # (::contents:start)

A robust Error subclass with error codes, typed debug values, and recursive
stack traces using native Error.cause.

## Usage

First, require me where you could throw errors:

```js
import YError from 'yerror';
```

Then, emit errors with a bonus: parameters!

```js
function doSomething(pay, action) {
  if (parseInt(pay, 10) !== pay) {
    throw new YError('E_BAD_PAY', [pay, action]);
  }
}

doSomething('nuts', 'code');

// YError: E_BAD_PAY (["nuts", "code"])
//   at doSomething (/home/nfroidure/nfroidure/yerror/test.js:5:11)
//   at Object.<anonymous> (/home/nfroidure/nfroidure/yerror/test.js:9:1)
//   (...)
```

You don't have to use constant like error messages, we use this convention
mainly for i18n reasons.

Also, you could want to wrap errors and keep a valuable stack trace:

```js
function doSomethingAsync(pay, action) {
  return new Promise(function (resolve, reject) {
    try {
      doSomething(pay, action);
      resolve();
    } catch (err) {
      reject(YError.bump(err));
    }
  });
}

doSomethingAsync('nuts', 'code').catch(function (err) {
  console.log(err.stack);
});

// YError: E_BAD_PAY (nuts, code)
//    at doSomething (/home/nfroidure/nfroidure/yerror/test.js:5:11)
//    (...)
// Caused by: YError: E_BAD_TRANSACTION (pay)
//    at Function.YError.wrap (/home/nfroidure/nfroidure/yerror/src/index.js:41:12)
//    at /home/nfroidure/nfroidure/yerror/test.js:16:21
//    at doSomethingAsync (/home/nfroidure/nfroidure/yerror/test.js:11:11)
//    (...)
```

## Global Error Registry

You can now get full autocompletion and type-safety for your error codes and
their debug data.

```ts
import { YError } from 'yerror';

declare module 'yerror' {
  interface YErrorRegistry {
    E_USER_NOT_FOUND: [userId: string];
  }
}

// TypeScript will now enforce the correct arguments:
throw new YError('E_USER_NOT_FOUND', ['123']);

// Users of you own code will then be able to cast errors
try {
  getUser('123');
} catch (err) {
  if (hasYErrorCode(err, 'E_USER_NOT_FOUND')) {
    console.log(err.debug[0]);
  }
}
```

[//]: # (::contents:end)

# API
## Classes

<dl>
<dt><a href="#YError">YError</a> ⇐ <code>Error</code></dt>
<dd><p>A YError class able to contain some debug and
 print better stack traces</p>
</dd>
</dl>

## Functions

<dl>
<dt><a href="#printStackTrace">printStackTrace(err)</a> ⇒ <code>string</code></dt>
<dd><p>Allow to print a stack from anything (especially caught
 errors that may or may not contain errors 🤷).</p>
</dd>
<dt><a href="#hasYErrorCode">hasYErrorCode(err, code)</a> ⇒ <code>boolean</code></dt>
<dd><p>Allow to check a YError code and cast the error.</p>
</dd>
<dt><a href="#pickYErrorWithCode">pickYErrorWithCode(err, code)</a> ⇒ <code>boolean</code></dt>
<dd><p>Allow to check all errors for a YError code and return the casted the error.</p>
</dd>
</dl>

<a name="YError"></a>

## YError ⇐ <code>Error</code>
A YError class able to contain some debug and
 print better stack traces

**Kind**: global class  
**Extends**: <code>Error</code>  

* [YError](#YError) ⇐ <code>Error</code>
    * [new YError([errorCode], [debug], options)](#new_YError_new)
    * [.wrap(err, [errorCode], [debug])](#YError.wrap) ⇒ [<code>YError</code>](#YError)
    * [.cast(err, [errorCode], [debug])](#YError.cast) ⇒ [<code>YError</code>](#YError)
    * [.bump(err, [errorCode], [debug])](#YError.bump) ⇒ [<code>YError</code>](#YError)

<a name="new_YError_new"></a>

### new YError([errorCode], [debug], options)
Creates a new YError with an error code
 and some debug as debug values.


| Param | Type | Default | Description |
| --- | --- | --- | --- |
| [errorCode] | <code>string</code> | <code>&quot;&#x27;E_UNEXPECTED&#x27;&quot;</code> | The error code corresponding to the actual error |
| [debug] | <code>any</code> |  | Some additional debugging values The error options |
| options | <code>Object</code> |  | The error options |

<a name="YError.wrap"></a>

### YError.wrap(err, [errorCode], [debug]) ⇒ [<code>YError</code>](#YError)
Wraps any error and output a YError with an error
 code and some debug as debug values.

**Kind**: static method of [<code>YError</code>](#YError)  
**Returns**: [<code>YError</code>](#YError) - The wrapped error  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| err | <code>Error</code> |  | The error to wrap |
| [errorCode] | <code>string</code> | <code>&quot;&#x27;E_UNEXPECTED&#x27;&quot;</code> | The error code corresponding to the actual error |
| [debug] | <code>any</code> |  | Some additional debugging values |

<a name="YError.cast"></a>

### YError.cast(err, [errorCode], [debug]) ⇒ [<code>YError</code>](#YError)
Return a YError as is or wraps any other error and output
 a YError with a code and some debug as debug values.

**Kind**: static method of [<code>YError</code>](#YError)  
**Returns**: [<code>YError</code>](#YError) - The wrapped error  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| err | <code>Error</code> |  | The error to cast |
| [errorCode] | <code>string</code> | <code>&quot;&#x27;E_UNEXPECTED&#x27;&quot;</code> | The error code corresponding to the actual error |
| [debug] | <code>any</code> |  | Some additional debugging values |

<a name="YError.bump"></a>

### YError.bump(err, [errorCode], [debug]) ⇒ [<code>YError</code>](#YError)
Same than `YError.wrap()` but preserves the code
 and the debug values of the error if it is
 already an instance of the YError constructor.

**Kind**: static method of [<code>YError</code>](#YError)  
**Returns**: [<code>YError</code>](#YError) - The wrapped error  

| Param | Type | Default | Description |
| --- | --- | --- | --- |
| err | <code>Error</code> |  | The error to bump |
| [errorCode] | <code>string</code> | <code>&quot;&#x27;E_UNEXPECTED&#x27;&quot;</code> | The error code corresponding to the actual error |
| [debug] | <code>any</code> |  | Some additional debugging values |

<a name="printStackTrace"></a>

## printStackTrace(err) ⇒ <code>string</code>
Allow to print a stack from anything (especially caught
 errors that may or may not contain errors 🤷).

**Kind**: global function  
**Returns**: <code>string</code> - The stack trace if any  

| Param | Type | Description |
| --- | --- | --- |
| err | <code>Error</code> | The error to print |

<a name="hasYErrorCode"></a>

## hasYErrorCode(err, code) ⇒ <code>boolean</code>
Allow to check a YError code and cast the error.

**Kind**: global function  
**Returns**: <code>boolean</code> - The result  

| Param | Type | Description |
| --- | --- | --- |
| err | <code>Error</code> | The error to cast |
| code | <code>Error</code> | The code to check |

<a name="pickYErrorWithCode"></a>

## pickYErrorWithCode(err, code) ⇒ <code>boolean</code>
Allow to check all errors for a YError code and return the casted the error.

**Kind**: global function  
**Returns**: <code>boolean</code> - The result  

| Param | Type | Description |
| --- | --- | --- |
| err | <code>Error</code> | The error to cast |
| code | <code>Error</code> | The code to check |


# Authors
- [Nicolas Froidure (formerly at SimpliField)](http://insertafter.com/en/index.html)

# License
[MIT](https://github.com/nfroidure/yerror/blob/main/LICENSE)

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