fix(replay): Distinguish worker load failures from page-teardown aborts

CHANGELOG.md

@@ -12,6 +12,10 @@ Work in this release was contributed by @PeterWadie and @akshitsinha. Thank you
 
   The SvelteKit SDK now supports SvelteKit 3, including client-side pageload and navigation tracing and server-side native tracing, alongside continued SvelteKit 2 support. No Sentry-specific setup changes are required. The SDK detects your SvelteKit version and picks the right implementation automatically.
 
+### Other Changes
+
+- fix(replay): Distinguish compression worker load failures from page-teardown aborts ([#22378](https://github.com/getsentry/sentry-javascript/pull/22378))
+
 ## 10.66.0
 
 - chore(node-core): Deprecate `@sentry/node-core` package ([#22285](https://github.com/getsentry/sentry-javascript/pull/22285))

packages/replay-internal/src/eventBuffer/WorkerHandler.ts

@@ -1,7 +1,37 @@
+import { WINDOW } from '../constants';
 import { DEBUG_BUILD } from '../debug-build';
 import type { WorkerRequest, WorkerResponse } from '../types';
 import { debug } from '../util/logger';
 
+/**
+ * Build the error thrown when the compression worker fails to load.
+ *
+ * The worker's `error` event is a bare `Event` (not an `ErrorEvent`) when the
+ * script fails to *load* — it carries no `message`, so we can't read a cause
+ * off it. Rather than always blaming CSP/network, we check whether the document
+ * is no longer visible: when the page is navigating away or backgrounded, an
+ * in-flight worker fetch is aborted and this error is expected teardown noise,
+ * not a real load failure. Distinguishing the two keeps the captured signal
+ * accurate across browsers (this fires on Safari, Chrome, Firefox alike).
+ */
+function _getWorkerLoadError(error: unknown): Error {
+  if (error instanceof ErrorEvent && error.message) {
+    return new Error(`Failed to load Replay compression worker: ${error.message}`);
+  }
+
+  // `document` may be undefined in non-browser worker/SSR contexts.
+  const isDocumentHidden = WINDOW.document && WINDOW.document.visibilityState !== 'visible';
+  if (isDocumentHidden) {
+    return new Error(
+      'Failed to load Replay compression worker: the page was hidden or unloaded before the worker loaded.',
+    );
+  }
+
+  return new Error(
+    'Failed to load Replay compression worker: Unknown error. This can happen due to CSP policy restrictions, network issues, or the worker script failing to load.',
+  );
+}
+
 interface PendingRequest {
   method: WorkerRequest['method'];
   resolve: (value: unknown) => void;
@@ -56,11 +86,7 @@ export class WorkerHandler {
         'error',
         error => {
           DEBUG_BUILD && debug.warn('Failed to load Replay compression worker', error);
-          reject(
-            new Error(
-              `Failed to load Replay compression worker: ${error instanceof ErrorEvent && error.message ? error.message : 'Unknown error. This can happen due to CSP policy restrictions, network issues, or the worker script failing to load.'}`,
-            ),
-          );
+          reject(_getWorkerLoadError(error));
         },
         { once: true },
       );

packages/replay-internal/test/unit/eventBuffer/WorkerHandler.test.ts

@@ -2,7 +2,7 @@
  * @vitest-environment jsdom
  */
 
-import { describe, expect, it } from 'vitest';
+import { afterEach, describe, expect, it } from 'vitest';
 import { WorkerHandler } from '../../../src/eventBuffer/WorkerHandler';
 import type { WorkerResponse } from '../../../src/types';
 
@@ -62,6 +62,16 @@ class MockWorker implements Pick<Worker, 'addEventListener' | 'removeEventListen
     this._dispatch('message', { data: response } as MessageEvent);
   }
 
+  /** Dispatch the worker's readiness message (consumed by `ensureReady`). */
+  public dispatchReady(success = true): void {
+    this._dispatch('message', { data: { success } } as MessageEvent);
+  }
+
+  /** Dispatch an `error` event, as fired when the worker script fails to load. */
+  public dispatchError(event: Event): void {
+    this._dispatch('error', event as MessageEvent);
+  }
+
   public get pendingCount(): number {
     return this._pendingRequests.length;
   }
@@ -171,4 +181,56 @@ describe('Unit | eventBuffer | WorkerHandler', () => {
     expect(worker.terminated).toBe(true);
     expect(worker.listenerCount).toBe(0);
   });
+
+  describe('ensureReady', () => {
+    const originalVisibility = Object.getOwnPropertyDescriptor(Document.prototype, 'visibilityState');
+
+    const setVisibility = (state: DocumentVisibilityState): void => {
+      Object.defineProperty(document, 'visibilityState', { configurable: true, get: () => state });
+    };
+
+    afterEach(() => {
+      if (originalVisibility) {
+        Object.defineProperty(Document.prototype, 'visibilityState', originalVisibility);
+      }
+    });
+
+    it('resolves once the worker reports readiness', async () => {
+      const { worker, handler } = makeHandler();
+      const ready = handler.ensureReady();
+      worker.dispatchReady();
+      await expect(ready).resolves.toBeUndefined();
+    });
+
+    it('caches the ready promise so listeners are only attached once', () => {
+      const { handler } = makeHandler();
+      expect(handler.ensureReady()).toBe(handler.ensureReady());
+    });
+
+    it("uses an ErrorEvent's message when one is present", async () => {
+      const { worker, handler } = makeHandler();
+      const ready = handler.ensureReady();
+      worker.dispatchError(new ErrorEvent('error', { message: 'CSP blocked worker-src' }));
+      await expect(ready).rejects.toThrow('Failed to load Replay compression worker: CSP blocked worker-src');
+    });
+
+    it('attributes a bare error event to teardown when the document is hidden', async () => {
+      setVisibility('hidden');
+      const { worker, handler } = makeHandler();
+      const ready = handler.ensureReady();
+      // A load failure fires a plain Event with no message (Safari/Chrome/Firefox alike).
+      worker.dispatchError(new Event('error'));
+      await expect(ready).rejects.toThrow(
+        'Failed to load Replay compression worker: the page was hidden or unloaded before the worker loaded.',
+      );
+    });
+
+    it('falls back to the generic message for a bare error event while visible', async () => {
+      setVisibility('visible');
+      const { worker, handler } = makeHandler();
+      const ready = handler.ensureReady();
+      worker.dispatchError(new Event('error'));
+      await expect(ready).rejects.toThrow(/Unknown error\. This can happen due to CSP policy restrictions/);
+    });
+  });
 });