dotnet/aspnetcore · error · Error

Blazor WebAssembly has not initialized.

Error message

Blazor WebAssembly has not initialized.

What it means

Thrown by updateWebAssemblyRootComponents when startPromise exists but Blazor._internal.updateRootComponents is not yet assigned. That hook is installed midway through startCore (Boot.WebAssembly.Common.ts:167), so calling the update API before startCore reaches that line finds the function undefined.

Source

Thrown at src/Components/Web.JS/src/Boot.WebAssembly.Common.ts:250

  })();
  return platformLoadPromise;
}

export function hasStartedLoadingWebAssemblyPlatform(): boolean {
  return platformLoadPromise !== undefined;
}

export function hasLoadedWebAssemblyPlatform(): boolean {
  return loadedWebAssemblyPlatform;
}

export function updateWebAssemblyRootComponents(operations: string, webAssemblyState: string): void {
  if (!startPromise) {
    throw new Error('Blazor WebAssembly has not started.');
  }

  if (!Blazor._internal.updateRootComponents) {
    throw new Error('Blazor WebAssembly has not initialized.');
  }

  if (!started) {
    scheduleAfterStarted(operations, webAssemblyState);
  } else {
    Blazor._internal.updateRootComponents(operations, webAssemblyState);
  }
}

async function scheduleAfterStarted(operations: string, webAssemblyState: string): Promise<void> {
  await startPromise;

  if (!Blazor._internal.updateRootComponents) {
    throw new Error('Blazor WebAssembly has not initialized.');
  }

  Blazor._internal.updateRootComponents(operations, webAssemblyState);
}

View on GitHub (pinned to 294cab2f9b)

Solutions

1. Await startPromise (i.e. await Blazor.start()) before issuing root-component updates, so startCore has finished wiring hooks.
2. Type-guard the call: if (typeof Blazor._internal.updateRootComponents === 'function') { ... } before invoking.

Example fix

// before: update races the boot body
Blazor.start();
Blazor._internal.updateRootComponents(ops, state); // _internal.updateRootComponents undefined -> throws

// after
await Blazor.start();
if (typeof Blazor._internal.updateRootComponents === 'function') {
  Blazor._internal.updateRootComponents(ops, state);
}

function isUpdateHookReady(): boolean {
  return typeof (Blazor as any)._internal?.updateRootComponents === 'function';
}

if (isUpdateHookReady()) {
  Blazor._internal.updateRootComponents(ops, state);
} else {
  console.warn('WebAssembly boot not yet initialized; deferring update.');
}

function hasUpdateRootComponents(b: any): b is { _internal: { updateRootComponents: (ops: string, state: string) => void } } {
  return typeof b?._internal?.updateRootComponents === 'function';
}

try {
  Blazor._internal.updateRootComponents(ops, state);
} catch (e) {
  if (/has not initialized/.test((e as Error).message)) {
    await Blazor.start();
    Blazor._internal.updateRootComponents(ops, state);
  } else throw e;
}

When it happens

Trigger: Invoking updateWebAssemblyRootComponents while startCore is still in flight (e.g. during platform load, before the updateRootComponents hook is wired up), but after startWebAssembly has set startPromise.

Common situations: A root-component update fired during the WebAssembly boot window; navigation or render-mode switching that pushes updates before the runtime hooked up the interop; tests that call update immediately after start() without awaiting.

Related errors

• Blazor WebAssembly has not started.
• WebAssembly options have already been configured.
• Blazor WebAssembly has already started.
• Failed to start platform. Reason: ${ex}
• Blazor has already started.

AI-assisted analysis of dotnet/aspnetcore@294cab2f9b (2026-08-06). Data as JSON: /api/errors/99728fbe2221b09b. Report an issue: GitHub.