From 26209c4f4565b322adbbd2330c1063c352d6b6a5 Mon Sep 17 00:00:00 2001
From: Sen Chang <sen.chang@livekit.io>
Date: Thu, 22 Oct 2026 10:01:33 -0700
Subject: [PATCH 1/3] Reject asset load failures with an Error naming the URL

A failed background image or tasks-vision fileset reached callers as a bare
DOM Event, with no message, so `e.message` was undefined and logs printed
"Event". The image loader rejected with the <img> error event directly; it
now rejects with an Error naming the path. MediaPipe rejects a failed
wasm-loader <script> with that tag's error event, so init() converts it into
an Error naming the script URL. Both keep the original event as `cause`.

Adds e2e case B4, which points the fileset at a 404 and asserts the
rejection is an Error naming it, and extends D6 to assert the logged image
failure names the image. Both fail without this change.

Fixes #142
---
 .changeset/name-failed-assets.md          |  5 +++++
 e2e/README.md                             |  6 +++---
 e2e/specs/background.spec.ts              |  6 ++++++
 e2e/specs/lifecycle.spec.ts               | 21 +++++++++++++++++++++
 src/transformers/BackgroundTransformer.ts | 13 ++++++++++++-
 tsconfig.json                             |  2 +-
 6 files changed, 48 insertions(+), 5 deletions(-)
 create mode 100644 .changeset/name-failed-assets.md

diff --git a/.changeset/name-failed-assets.md b/.changeset/name-failed-assets.md
new file mode 100644
index 0000000..44796c5
--- /dev/null
+++ b/.changeset/name-failed-assets.md
@@ -0,0 +1,5 @@
+---
+'@livekit/track-processors': patch
+---
+
+Reject with an `Error` naming the URL when the MediaPipe fileset or a background image fails to load, instead of a bare DOM `Event`
diff --git a/e2e/README.md b/e2e/README.md
index 99ce1f1..e6d4776 100644
--- a/e2e/README.md
+++ b/e2e/README.md
@@ -33,14 +33,14 @@ Chrome only for now. Firefox, WebKit and BrowserStack devices need their own cal
 
 ## What's covered
 
-Seventeen cases across eleven concerns.
+Twenty cases.
 
 | Spec | IDs | Concern |
 | --- | --- | --- |
 | `capability.spec.ts` | A1, A1b, A3, A4 | Support predicates; both pipelines selected and working |
-| `lifecycle.spec.ts` | B1, B2 | Attach produces blurred frames; detach restores them |
+| `lifecycle.spec.ts` | B1, B2, B3, B4 | Attach produces blurred frames; detach restores them and releases the WebGL context; a missing fileset rejects with an `Error` naming it |
 | `modes.spec.ts` | C1, C1b, C3 | Switching lands correctly, publishes no intermediate frame, and `disabled` is true passthrough |
-| `background.spec.ts` | D1, D5, D6 | Image composited behind the subject; fetched once; a failing image at construction is logged |
+| `background.spec.ts` | D1, D5, D6 | Image composited behind the subject; fetched once; a failing image at construction is logged by name |
 | `geometry.spec.ts` | E1 | Output dimensions follow the source at three resolutions |
 | `performance.spec.ts` | G1 | `onFrameProcessed` timings are coherent at a usable frame rate |
 
diff --git a/e2e/specs/background.spec.ts b/e2e/specs/background.spec.ts
index 4827a0e..3c6ad04 100644
--- a/e2e/specs/background.spec.ts
+++ b/e2e/specs/background.spec.ts
@@ -133,5 +133,11 @@ test.describe('virtual background', () => {
     // uncaught error with no message.
     expect(app.pageErrors, 'uncaught page errors').toEqual([]);
     expect(await page.evaluate(() => window.harness.lastError()), 'harness logged an error').toBeNull();
+
+    // #142: the logged failure names the image rather than printing a bare DOM Event.
+    expect(
+      app.consoleErrors.some((line) => line.includes('missing-bg.png')),
+      `no console error named the image: ${JSON.stringify(app.consoleErrors)}`,
+    ).toBe(true);
   });
 });
diff --git a/e2e/specs/lifecycle.spec.ts b/e2e/specs/lifecycle.spec.ts
index 40064bf..a616255 100644
--- a/e2e/specs/lifecycle.spec.ts
+++ b/e2e/specs/lifecycle.spec.ts
@@ -120,4 +120,25 @@ test.describe('processor lifecycle', () => {
       .poll(() => page.evaluate(() => window.harness.counters().webgl.contextsLost))
       .toBeGreaterThanOrEqual(before + cycles);
   });
+
+  // #142: MediaPipe rejects a failed wasm-loader script with its DOM Event, which has no message.
+  test('B4: a fileset that fails to load rejects with an Error naming its URL', async ({ app }) => {
+    const { page } = app;
+    await page.route('**/missing-wasm/**', (route) => route.fulfill({ status: 404 }));
+    await app.goto({ backdrop: 'checker', motion: 'static', wasm: '/missing-wasm' });
+    await startCamera(page);
+
+    const err = await page.evaluate(() =>
+      window.harness.media.setVideoProcessorEnabled(true).then(
+        () => null,
+        (e: unknown) => ({
+          isError: e instanceof Error,
+          message: String((e as Error).message),
+        }),
+      ),
+    );
+    expect(err, 'attaching with a missing fileset resolved').not.toBeNull();
+    expect(err?.isError, 'rejection value is an Error').toBe(true);
+    expect(err?.message).toContain('/missing-wasm/');
+  });
 });
diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index 8c8823a..abbd637 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -78,6 +78,16 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
       runningMode: 'VIDEO',
       outputCategoryMask: true,
       outputConfidenceMasks: false,
+    }).catch((err) => {
+      // MediaPipe loads its wasm loader through a <script> tag and rejects with that tag's error
+      // Event, which has no message. The script's URL is the only thing identifying the failure.
+      if (err instanceof Event) {
+        const src = err.target instanceof HTMLScriptElement ? err.target.src : 'unknown URL';
+        throw new Error(`Failed to load the MediaPipe tasks-vision fileset from ${src}`, {
+          cause: err,
+        });
+      }
+      throw err;
     });
 
     // Skip loading the image here if update already loaded the image below
@@ -112,7 +122,8 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
       await new Promise((resolve, reject) => {
         img.crossOrigin = 'Anonymous';
         img.onload = () => resolve(img);
-        img.onerror = (err) => reject(err);
+        img.onerror = (event) =>
+          reject(new Error(`Failed to load background image from ${path}`, { cause: event }));
         img.src = path;
       });
       const imageData = await createImageBitmap(img);
diff --git a/tsconfig.json b/tsconfig.json
index 65dfaff..f432389 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "lib": ["DOM", "ES2018"],
+    "lib": ["DOM", "ES2018", "ES2022.Error"],
     "target": "ES2018" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */,
     "module": "ES2020" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */,
     "rootDir": "./",

From fc6c8027f9f7461d467fdbd38aa8bc9d46742586 Mon Sep 17 00:00:00 2001
From: Sen Chang <sen.chang@livekit.io>
Date: Thu, 22 Oct 2026 15:50:41 -0700
Subject: [PATCH 2/3] Assign cause directly so older browsers keep it

Browsers without support for the Error constructor's cause option drop it
silently, so the original Event was lost there. cause is now assigned on the
error after construction, and the ES2022.Error lib entry is no longer needed.
---
 src/transformers/BackgroundTransformer.ts | 14 ++++++++++----
 tsconfig.json                             |  2 +-
 2 files changed, 11 insertions(+), 5 deletions(-)

diff --git a/src/transformers/BackgroundTransformer.ts b/src/transformers/BackgroundTransformer.ts
index abbd637..1877a27 100644
--- a/src/transformers/BackgroundTransformer.ts
+++ b/src/transformers/BackgroundTransformer.ts
@@ -24,6 +24,14 @@ export type BackgroundOptions = {
   onFrameProcessed?: (stats: FrameProcessingStats) => void;
 };
 
+/**
+ * `cause` is assigned rather than passed to the constructor, because browsers without support for
+ * the `cause` option ignore it.
+ */
+function errorWithCause(message: string, cause: unknown) {
+  return Object.assign(new Error(message), { cause });
+}
+
 export default class BackgroundProcessor extends VideoTransformer<BackgroundOptions> {
   static get isSupported() {
     return (
@@ -83,9 +91,7 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
       // Event, which has no message. The script's URL is the only thing identifying the failure.
       if (err instanceof Event) {
         const src = err.target instanceof HTMLScriptElement ? err.target.src : 'unknown URL';
-        throw new Error(`Failed to load the MediaPipe tasks-vision fileset from ${src}`, {
-          cause: err,
-        });
+        throw errorWithCause(`Failed to load the MediaPipe tasks-vision fileset from ${src}`, err);
       }
       throw err;
     });
@@ -123,7 +129,7 @@ export default class BackgroundProcessor extends VideoTransformer<BackgroundOpti
         img.crossOrigin = 'Anonymous';
         img.onload = () => resolve(img);
         img.onerror = (event) =>
-          reject(new Error(`Failed to load background image from ${path}`, { cause: event }));
+          reject(errorWithCause(`Failed to load background image from ${path}`, event));
         img.src = path;
       });
       const imageData = await createImageBitmap(img);
diff --git a/tsconfig.json b/tsconfig.json
index f432389..65dfaff 100644
--- a/tsconfig.json
+++ b/tsconfig.json
@@ -1,6 +1,6 @@
 {
   "compilerOptions": {
-    "lib": ["DOM", "ES2018", "ES2022.Error"],
+    "lib": ["DOM", "ES2018"],
     "target": "ES2018" /* Specify ECMAScript target version: 'ES3' (default), 'ES5', 'ES2015', 'ES2016', 'ES2017', 'ES2018', 'ES2019', 'ES2020', or 'ESNEXT'. */,
     "module": "ES2020" /* Specify module code generation: 'none', 'commonjs', 'amd', 'system', 'umd', 'es2015', 'es2020', or 'ESNext'. */,
     "rootDir": "./",

From d3f489b01cc28dfc30ecd0b2a84fc7b413a44f31 Mon Sep 17 00:00:00 2001
From: Sen Chang <sen.chang@livekit.io>
Date: Thu, 22 Oct 2026 16:15:25 -0700
Subject: [PATCH 3/3] Assert the original Event survives as cause in B4

B4 now checks that the fileset rejection carries the script tag's error
Event as cause. It fails if errorWithCause stops setting cause.
---
 e2e/specs/lifecycle.spec.ts | 17 +++++++++++++----
 1 file changed, 13 insertions(+), 4 deletions(-)

diff --git a/e2e/specs/lifecycle.spec.ts b/e2e/specs/lifecycle.spec.ts
index a616255..9e4ba9b 100644
--- a/e2e/specs/lifecycle.spec.ts
+++ b/e2e/specs/lifecycle.spec.ts
@@ -131,14 +131,23 @@ test.describe('processor lifecycle', () => {
     const err = await page.evaluate(() =>
       window.harness.media.setVideoProcessorEnabled(true).then(
         () => null,
-        (e: unknown) => ({
-          isError: e instanceof Error,
-          message: String((e as Error).message),
-        }),
+        (e: unknown) => {
+          const cause = (e as { cause?: unknown }).cause;
+          return {
+            isError: e instanceof Error,
+            message: String((e as Error).message),
+            causeIsEvent: cause instanceof Event,
+            causeTarget:
+              cause instanceof Event ? (cause.target as Element | null)?.tagName : undefined,
+          };
+        },
       ),
     );
     expect(err, 'attaching with a missing fileset resolved').not.toBeNull();
     expect(err?.isError, 'rejection value is an Error').toBe(true);
     expect(err?.message).toContain('/missing-wasm/');
+    // The browser's original error stays reachable for callers that need more than the message.
+    expect(err?.causeIsEvent, 'cause is the original Event').toBe(true);
+    expect(err?.causeTarget).toBe('SCRIPT');
   });
 });