dotnet/aspnetcore · error · Error

WebAssembly options have already been configured.

Error message

WebAssembly options have already been configured.

What it means

Thrown by setWebAssemblyOptions when the module-level 'options' variable is already set. WebAssembly options are configured once during boot; a second call indicates the WebAssembly platform was asked to configure twice.

Source

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

  firstUpdate = false;
}

let resolveInitializersPromise: (value: void) => void;
const initializersPromise = new Promise<void>(resolve => {
  resolveInitializersPromise = resolve;
});

export function isFirstUpdate() {
  return firstUpdate;
}

export function setWaitForRootComponents(): void {
  waitForRootComponents = true;
}

export function setWebAssemblyOptions(initializersReady: Promise<Partial<WebAssemblyStartOptions>>) {
  if (options) {
    throw new Error('WebAssembly options have already been configured.');
  }
  setOptions(initializersReady);


  async function setOptions(initializers: Promise<Partial<WebAssemblyStartOptions>>) {
    const configuredOptions = await initializers;
    options = configuredOptions;
    resolveInitializersPromise();
  }
}

export function startWebAssembly(components: RootComponentManager<WebAssemblyComponentDescriptor>, options: WebAssemblyServerOptions | undefined): Promise<void> {
  if (startPromise !== undefined) {
    throw new Error('Blazor WebAssembly has already started.');
  }

  startPromise = new Promise(startCore.bind(null, components, options));

View on GitHub (pinned to 294cab2f9b)

Solutions

1. Start WebAssembly exactly once; guard the call site before configuring.
2. If hosting WebAssembly inside Web, let the Web boot path configure WebAssembly options and do not call Blazor.start() again for the WebAssembly bundle.
3. Disable autostart on blazor.webassembly.js when starting manually.

Example fix

// before
Blazor.start({ webAssembly: { ... } });
Blazor.start({ webAssembly: { ... } }); // throws

// after
if (!window.__wasmConfigured) {
  window.__wasmConfigured = true;
  Blazor.start({ webAssembly: { ... } });
}

function configureWasmOnce(opts: Partial<WebAssemblyStartOptions>) {
  if ((window as any).__wasmOptionsConfigured) return;
  (window as any).__wasmOptionsConfigured = true;
  Blazor.start({ webAssembly: opts });
}

function wasmOptionsConfigured(): boolean {
  return !!(window as any).__wasmOptionsConfigured;
}

try {
  Blazor.start({ webAssembly: opts });
} catch (e) {
  if (/already been configured/.test((e as Error).message)) return;
  throw e;
}

When it happens

Trigger: Calling Blazor.start({ webAssembly: {...} }) twice, or Boot.Web.ts calling setWebAssemblyOptions while Boot.WebAssembly.ts has already configured it, or an initializer re-invoking the configuration.

Common situations: Hosting a Blazor WebAssembly app under a Blazor Web App shell where both bundles call into WebAssembly config; manual start plus autostart; HMR re-running the WebAssembly boot module.

Related errors

• Circuit options have already been configured.
• Blazor WebAssembly has already started.
• Blazor has already started.
• Blazor Server has already started.
• Blazor has already started.

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