ReactiveX/rxjs · critical · AggregateError

Cannot initialize @rxjs/observable-polyfill and could not fu

Error message

Cannot initialize @rxjs/observable-polyfill and could not fully restore the realm

What it means

Thrown when installing the @rxjs/observable-polyfill failed and the subsequent rollback of already-applied patches also failed, so the realm is left partially patched. The library aggregates the original error plus all rollback errors into one AggregateError so nothing is silently swallowed.

Source

Thrown at packages/observable-polyfill/src/index.ts:1368

      applied.push(installation);
    }
  } catch (error) {
    const rollbackErrors: unknown[] = [];
    for (let index = applied.length - 1; index >= 0; index--) {
      const installation = applied[index]!;
      try {
        if (installation.previous) {
          Object.defineProperty(installation.target, installation.key, installation.previous);
        } else {
          Reflect.deleteProperty(installation.target, installation.key);
        }
      } catch (rollbackError) {
        rollbackErrors.push(rollbackError);
      }
    }

    if (rollbackErrors.length > 0) {
      throw new AggregateError(
        [error, ...rollbackErrors],
        'Cannot initialize @rxjs/observable-polyfill and could not fully restore the realm'
      );
    }
    throw error;
  }
}

function initializeObservablePolyfill(): void {
  const installations: PropertyInstallation[] = [];
  const activeObservable = (globalThis as typeof globalThis & { Observable?: ObservableCtor }).Observable;

  if (activeObservable === undefined) {
    const AbortControllerCtor = globalThis.AbortController;
    const abortDescriptor = AbortControllerCtor && Object.getOwnPropertyDescriptor(AbortControllerCtor.prototype, 'abort');
    if (!AbortControllerCtor || !abortDescriptor || typeof abortDescriptor.value !== 'function') {
      throw new TypeError('Cannot initialize @rxjs/observable-polyfill: AbortController.prototype.abort is unavailable');
    }

View on GitHub (pinned to 54796b38a5)

Solutions

Inspect error.errors array: the first element is the root installation failure, the rest are rollback failures — fix the root cause first
Ensure globalThis.AbortController exists with a prototype-level abort method before importing the polyfill
Ensure Observable/AbortController prototype properties are configurable and not frozen (delete Object.freeze on globalThis or its prototypes)
Ensure only one polyfill installation runs (no concurrent import of a competing Observable polyfill)

Example fix

// before
import '@rxjs/observable-polyfill'; // throws AggregateError in frozen realm
// after
if (!globalThis.Observable) {
  Object.getOwnPropertyDescriptor(AbortController.prototype, 'abort'); // sanity check
  import('@rxjs/observable-polyfill');
}

Defensive patterns

Strategy: try-catch

Validate before calling

const abortOk = typeof globalThis.AbortController === 'function' &&
  typeof Object.getOwnPropertyDescriptor(AbortController.prototype, 'abort')?.value === 'function';
if (!globalThis.Observable && !abortOk) throw new Error('Polyfill prerequisites missing');

Try / catch

try {
  await import('@rxjs/observable-polyfill');
} catch (e) {
  if (e instanceof AggregateError) {
    console.error('root cause:', e.errors[0]);
    // realm is partially patched: reload/restart the realm rather than continuing
  }
  throw e;
}

Prevention

Check AbortController and Observable descriptors before importing the polyfill
Never freeze globalThis or Observable/AbortController prototypes
Run polyfill installation once, at application entry, before any concurrent imports

When it happens

Trigger: Importing or calling install() of @rxjs/observable-polyfill in an environment where Observable is missing and either AbortController patching or a later installation step throws, and one of the already-installed property installations cannot be removed during rollback (e.g. frozen prototypes, non-configurable properties, or a second polyfill racing).

Common situations: Test realms or sandboxes with sealed/frozen globals, two polyfills installing simultaneously, hostile environments (SSR frameworks freezing globalThis), or partial platform shims that define non-configurable descriptors.

Related errors

AI-assisted analysis of ReactiveX/rxjs@54796b38a5 (2026-08-28). Data as JSON: /api/errors/99742e4d02d9de6c. Report an issue: GitHub.