And use `OError.getFullStack` to reconstruct the full stack, including the tagged errors:
```
Error: not found
at process.nextTick (repl:8:18)
at process._tickCallback (internal/process/next_tick.js:61:11)
TaggedError
at demoDatabase.findUser (repl:3:37)
at process.nextTick (repl:8:9)
at process._tickCallback (internal/process/next_tick.js:61:11)
TaggedError
at sayHi2 (repl:3:46)
at demoDatabase.findUser (repl:3:21)
at process.nextTick (repl:8:9)
at process._tickCallback (internal/process/next_tick.js:61:11)
```
The full stack contains the original error's stack and also the `TaggedError` stacks. There's some redundancy, but it's better to have too much information than too little.
### Adding More Info
You can add more information at each `tag` call site: a message and an `info` object with custom properties.
```js
function sayHi3(userId, callback) {
demoDatabase.findUser(userId, (err, user) => {
if (err) return callback(OError.tag(err, 'failed to find user', { userId }))
The `OError.getFullInfo` property merges all of the `info`s from the tags together into one object. This logs a full stack trace with `failed to ...` annotations and an `info` object that contains the `userId` that it failed to find:
```
Error: not found
at process.nextTick (repl:8:18)
at process._tickCallback (internal/process/next_tick.js:61:11)
TaggedError: failed to find user
at demoDatabase.findUser (repl:3:37)
at process.nextTick (repl:8:9)
at process._tickCallback (internal/process/next_tick.js:61:11)
TaggedError: failed to say hi
at sayHi3 (repl:3:12)
at demoDatabase.findUser (repl:3:21)
at process.nextTick (repl:8:9)
at process._tickCallback (internal/process/next_tick.js:61:11)
Logging this information (or reporting it to an error monitoring service) hopefully gives you a good start to figuring out what went wrong.
### `async`/`await`
The `OError.tag` approach works with both async/await and callback-oriented code. When using async/await, the pattern is to catch an error, tag it and rethrow:
The resulting full stack trace points to `sayHi4` in `main`, as expected:
```
Error: not found
at process.nextTick (repl:8:18)
at process._tickCallback (internal/process/next_tick.js:61:11)
TaggedError: failed to find user
at sayHi4 (repl:6:18)
at process._tickCallback (internal/process/next_tick.js:68:7)
TaggedError: failed to say hi
at main (repl:5:12)
at process._tickCallback (internal/process/next_tick.js:68:7)
{ userId: 43 }
```
### Better Async Stack Traces in Node 12+
The above output is from node 10. Node 12 has improved stack traces for async code that uses native promises. However, until your whole stack, including all libraries, is using async/await and native promises, you're still likely to get unhelpful stack traces. So, the tagging approach still adds value, even in node 12. (And the `info` from tagging can add value even to a good stack trace, because it can contain clues about the input the caused the error.)
Some libraries, such as `ioredis`, may return the same `Error` instance to multiple callbacks. In this case, the tags may be misleading, because they will be a mixture of the different 'stacks' that lead to the error. You can either accept this or choose to instead wrap the errors from these libraries with new `OError` instances using `withCause`.
In the worst case, a library that always returns a single instance of an error could cause a resource leak. To prevent this, `OError` will only add up to `OError.maxTags` (default 100) tags to a single Error instance.
Broadly speaking, there are two kinds of errors: those we try to recover from, and those for which we give up (i.e. a 5xx response in a web application). For the latter kind, we usually just want to log a message and stack trace useful for debugging, which `OError.tag` helps with.
To recover from an error, we usually need to know what kind of error it was and perhaps to check some of its properties. Defining a custom Error subclass is a good way to do this. Callers can check the type of the error either with `instanceof` or using a custom property, such as `code`.
With ES6 classes, creating a custom error subclass is mostly as simple as `extends Error`. One extra line is required to set the error's `name` appropriately, and inheriting from `OError` handles this implementation detail. Here's an example:
Whether for helping with error recovery or just for debugging, it is often helpful to include some of the state that caused the error in the error. One way to do this is to put it in the message, but this has a few problems:
- Even if the error is later handled and recovered from, we spend time stringifying the state to add it to the error message.
- Error monitoring systems often look at the message when trying to group similar errors together, and they can get confused by the ever-changing messages.
- When using structured logging, you lose the ability to easily query or filter the logs based on the state; instead clever regexes may be required to get it out of the messages.
Instead, `OError`s (and subclasses) support an `info` object that can contain arbitrary data. Using `info`, we might write the above example as:
```js
class UserNotFoundError extends OError {
constructor(userId) {
super('user not found', { userId })
}
}
try {
throw new UserNotFoundError(123)
} catch (error) {
console.error(OError.getFullStack(error))
console.error(OError.getFullInfo(error))
}
```
```
UserNotFoundError: user not found
at repl:2:9
...
{ userId: 123 }
```
The `OError.getFullInfo` helper merges the `info` on custom errors and any info added with `OError.tag` on its way up the stack. It is intended for use when logging errors. If trying to recover from an error that is known to be a `UserNotFoundError`, it is usually better to interrogate `error.info.userId` directly.
### Wrapping an Internal Error
Detecting a condition like 'user not found' in the example above often starts with an internal database error. It is possible to just let the internal database error propagate all the way up through the stack, but this makes the code more coupled to the internals of the database (or database driver). It is often cleaner to handle and wrap the internal error in one that is under your control. Tying up the examples above:
```js
async function sayHi5(userId) {
try {
const user = await demoDatabase.findUserAsync(userId)
return `Hi ${user.name}`
} catch (error) {
if (error.message === 'not found') {
throw new UserNotFoundError(userId).withCause(error)
}
}
}
async function main() {
try {
await sayHi5(43)
} catch (error) {
OError.tag(error, 'failed to say hi')
console.error(OError.getFullStack(error))
console.error(OError.getFullInfo(error))
}
}
main()
```
The output includes the wrapping error, the tag and the cause, together with the info:
```
UserNotFoundError: user not found
at sayHi5 (repl:7:13)
at process._tickCallback (internal/process/next_tick.js:68:7)
TaggedError: failed to say hi
at main (repl:5:12)
at process._tickCallback (internal/process/next_tick.js:68:7)
caused by:
Error: not found
at process.nextTick (repl:8:18)
at process._tickCallback (internal/process/next_tick.js:61:11)
