How can I preserve the original error when adding context to an async failure?

You can add a new, more specific error, but keep the caught value as its cause rather than replacing it. The wrapper gives a higher-level handler useful context, while the cause retains the underlying failure for inspection. In JavaScript, the Error constructor supports a cause option; Microsoft’s reference gives the pattern new Error('Loading records failed', { cause: err }). [S1]

For example, assuming readRecords() is an existing async operation:

async function loadRecords() {
  try {
    return await readRecords();
  } catch (err) {
    throw new Error("Loading records failed", { cause: err });
  }
}

This adds the context “Loading records failed” without pretending that message is the original failure. Choose wording that names the operation or stage, not a cause you have not established.

Let the wrapper continue to the layer that can decide what to do with it. That layer can inspect the wrapper’s message for operation context and its cause for the underlying value. For example:

async function refreshPage() {
  try {
    const records = await loadRecords();
    return showRecords(records);
  } catch (err) {
    console.error("Page refresh could not load records:", err);
    console.error("Underlying failure:", err.cause);
    throw err;
  }
}

Here, loadRecords() adds context, and refreshPage() receives that contextual error. This example logs both values and rethrows the same wrapper, so a still-higher caller can handle it too. The cited reference supports inspecting a wrapper’s cause; it does not prescribe where an application should log, display, or handle errors. [S1]

Make the wrapper message answer “which operation failed?” For instance, “Saving draft failed” is more useful than “Something went wrong.” Keep it factual: if you only know that saving failed, do not label the cause as a network problem unless you have evidence for that.

For handling, avoid treating message text as a stable identifier. The JavaScript reference advises using cause to distinguish errors rather than parsing messages. [S1] If your application needs to branch on a particular underlying failure, inspect a suitable property or type that your code actually defines or receives; the supplied reference does not establish what properties every possible cause will have. Also, wrapping is only useful if the value you caught is the failure you intend to preserve: pass that value through as cause instead of constructing an unrelated replacement.

Assuming the operation is saveDraft(), adapt the operation names and messages to your code:

async function saveDraftWithContext() {
  try {
    return await saveDraft();
  } catch (err) {
    throw new Error("Saving draft failed", { cause: err });
  }
}

async function publishDraft() {
  try {
    return await saveDraftWithContext();
  } catch (err) {
    console.error("Publishing could not save the draft:", err);
    console.error("Original cause:", err.cause);
    throw err;
  }
}

The path is: saveDraft() fails, saveDraftWithContext() adds a specific wrapper while retaining the caught value as cause, and publishDraft() receives that wrapper. [S1] Before adopting the pattern, check that the wrapper describes the stage that failed, the caught value is passed as the cause, and higher-level handling does not accidentally discard the wrapper or cause. The source explains the JavaScript cause pattern, but does not establish compatibility for every runtime or build target; check the environment your code must support. [S1]