JavaScript Promise finally Masks the Original Error: Keep Both Failures

Check what reaches the caller#

This wrapper treats cleanup as required. It runs cleanup once after work settles, propagates a single failure unchanged, and uses AggregateError when both steps fail. The work reason is first in errors; the cleanup reason is second. That order is the wrapper’s contract.

Save this as cleanup.mjs and run node cleanup.mjs. The example uses simulated writes and closes and was checked on Node.js 24.13.0 on macOS arm64.

1
import assert from "node:assert/strict";
2

3
async function runWithCleanup(work, cleanup) {
4
  let workFailed = false;
5
  let workError;
6
  try {
7
    return await work();
8
  } catch (error) {
9
    workFailed = true;
10
    workError = error;
11
    throw error;
12
  } finally {
13
    try {
14
      await cleanup();
15
    } catch (cleanupError) {
16
      if (!workFailed) throw cleanupError;
17
      throw new AggregateError(
18
        [workError, cleanupError],
19
        "Work and cleanup both failed",
20
      );
21
    }
22
  }
23
}
24

25
const writeError = new Error("write failed");
26
const closeError = new Error("close failed");
27
const write = async () => "saved";
28
const close = async () => {};
29
const failWrite = async () => { throw writeError; };
30
const failClose = async () => { throw closeError; };
31

32
await assert.rejects(failWrite().finally(failClose), e => e === closeError);
33
assert.equal(await runWithCleanup(write, close), "saved");
34
await assert.rejects(runWithCleanup(failWrite, close), e => e === writeError);
35
await assert.rejects(runWithCleanup(write, failClose), e => e === closeError);
36
await assert.rejects(runWithCleanup(failWrite, failClose), e =>
37
  e instanceof AggregateError &&
38
  e.errors[0] === writeError && e.errors[1] === closeError
39
);
40
await assert.rejects(
41
  runWithCleanup(() => Promise.reject(undefined), failClose),
42
  e => e instanceof AggregateError &&
43
    e.errors.length === 2 &&
44
    e.errors[0] === undefined && e.errors[1] === closeError
45
);
46
console.log("Six checks passed");

Expected output:

1
Six checks passed

The first assertion reproduces the masking with plain .finally(). The next four cover every success and failure combination in the wrapper. The last checks why the code uses a separate workFailed flag: a promise can reject with undefined, so testing the reason for truthiness would misclassify that rejection as success.

Keep return await work() inside the try. With return work(), the function can enter its finally block before the returned promise settles, and the local catch won’t capture a later rejection. Likewise, the cleanup callback must return or await all the cleanup work it owns. A detached promise is outside the wrapper’s error handling.

Decide which failure belongs in the result#

Use plain .finally() when cleanup cannot fail or when its failure should take precedence. Use the wrapper when cleanup is required and the caller can inspect AggregateError.errors. If existing callers branch on the type of the original error, handle the aggregate at that boundary before replacing the chain. For best-effort cleanup, catch and report the cleanup failure separately if the work’s outcome must remain unchanged.

This wrapper waits for the promise returned by work. If that promise rejects early while sibling operations are still using the resource, first wait for those operations to settle before cleanup.

References:

• ECMAScript: Promise.prototype.finally
• ECMAScript: AggregateError constructor