Wrap an error with cause
A lower-level operation fails and a higher-level API needs to add actionable context while retaining the original failure.
JavaScript · Class
Error
The Error constructor creates Error objects that describe failures. It accepts an optional message and an options object for preserving an underlying cause, and it can be called with or without new.
How it works
The Error constructor creates an Error object that describes a failure. It accepts an optional message and, in modern JavaScript, an options object whose cause property records the underlying value; it works with or without new, and the resulting object can be thrown or inspected.
Syntax
new Error()
new Error(message)
new Error(message, options)
Error()
Error(message)
Error(message, options)Parameters
| Name | Type | Description |
|---|---|---|
message | any | Optional human-readable description of the error. |
options | object | Optional object; its cause property identifies the specific underlying cause. |
Returns
A new Error object.
Key points
- Use Error to create an object representing a failure.
- The optional message argument supplies a readable description.
- The options argument can provide a cause property that records why the new error occurred.
- Use cause when wrapping a caught error with clearer context.
- The constructor works both as a function call and with new.
Common mistakes
- Calling Error() without new still creates an Error instance, so new is optional for this constructor.
- A cause property is not created unless the options argument is an object containing cause.
Example: Create an error with a cause
const error = new Error("Invalid configuration", {
cause: new TypeError("timeout must be a number"),
});
console.log(error.name); // "Error"
console.log(error.message); // "Invalid configuration"
console.log(error.cause instanceof TypeError); // trueCreates an Error with a human-readable message and preserves the underlying error as its cause.
When to use it
Throw a descriptive failure
Application code needs to signal invalid state or input to an enclosing try/catch boundary.
Create an inspectable error
A diagnostic layer needs a standard object with a message for logging or inspection.
Interview questions
QWhat does the Error constructor do, and is new required?
Error() creates an Error object, optionally using a human-readable message. The constructor may be called either as Error() or new Error(), and both forms create an Error instance.
Follow-up: How can an error preserve the original failure while adding context? Pass the original error as options.cause when constructing a new Error.
QWhat are the constructor's main arguments?
The first argument is message, an optional human-readable description. The second modern form is options, whose cause property stores the specific underlying cause for later inspection.
Follow-up: What happens when options lacks cause? The resulting Error has no cause property.
QWhy use the cause option when rethrowing an error?
Error can be thrown after construction, then caught and inspected through properties such as name, message, and cause. A wrapper error can therefore add a more useful message while retaining the original cause.
Follow-up: How would you distinguish an Error from an arbitrary caught value? Use the documented Error.isError() static method when available.
Related
AggregateErrorError.causeError.isError()Error.prototype.messageError.prototype.nameEvalErrorRangeErrorReferenceError