Error: cause

Value

The value that was passed to the Error() constructor in the options.cause argument. It may not be present.

Description

The value of cause can be of any type. You should not make assumptions that the error you caught has an Error as its cause, in the same way that you cannot be sure the variable bound in the catch statement is an Error either. The "Providing structured data as the error cause" example below shows a case where a non-error is deliberately provided as the cause.

The SuppressedError and AggregateError subclasses both serve the purpose of associating multiple errors. They both represent multiple failing sites: SuppressedError represents an error that occurred while handling another error, while AggregateError represents a collection of multiple, unrelated errors that occurred during the same operation. The cause property represents a single failing site, with the wrapper error only adding context to the cause and not representing an additional failure.

The following is typical usage of cause. There is a single failing site, which originates within mainLogic(). The throw new Error() statement merely wraps that original error to add context and does not constitute an additional failure.

try {
  mainLogic();
} catch (err) {
  throw new Error("Main logic failed", { cause: err });
}

The following is typical usage of SuppressedError. There are two failing sites: one within mainLogic() and one within cleanup(). The SuppressedError instance associates the two errors.

try {
  mainLogic();
} catch (primaryError) {
  try {
    cleanup();
  } catch (cleanupError) {
    throw new SuppressedError(
      cleanupError,
      primaryError,
      "Main logic failed; while handling that, cleanup also failed",
    );
  }
}

The following is typical usage of AggregateError. There are multiple failing sites within mainLogic(). The AggregateError instance associates all the errors.

function mainLogic() {
  const errors = [];
  try {
    operation1();
  } catch (e1) {
    errors.push(e1);
  }
  try {
    operation2();
  } catch (e2) {
    errors.push(e2);
  }
  if (errors.length > 0) {
    throw new AggregateError(errors, "Multiple operations failed");
  }
}

Examples

Rethrowing an error with a cause

It is sometimes useful to catch an error and re-throw it with a new message. In this case you should pass the original error into the constructor for the new Error, as shown.

try {
  connectToDatabase();
} catch (err) {
  throw new Error("Connecting to database failed.", { cause: err });
}

For a more detailed example see Error > Differentiate between similar errors.

Providing structured data as the error cause

Error messages written for human consumption may be inappropriate for machine parsing — since they're subject to rewording or punctuation changes that may break any existing parsing written to consume them. So when throwing an error from a function, as an alternative to a human-readable error message, you can instead provide the cause as structured data, for machine parsing.

function makeRSA(p, q) {
  if (!Number.isInteger(p) || !Number.isInteger(q)) {
    throw new Error("RSA key generation requires integer inputs.", {
      cause: { code: "NonInteger", values: [p, q] },
    });
  }
  if (!areCoprime(p, q)) {
    throw new Error("RSA key generation requires two co-prime integers.", {
      cause: { code: "NonCoprime", values: [p, q] },
    });
  }
  // rsa algorithm…
}

Specifications

Browser compatibility

See also

• Error.prototype.message
• Error.prototype.toString()