dotnet/aspnetcore · error · Error

Blazor has already started.

Error message

Blazor has already started.

What it means

Thrown by the local boot() in Boot.Server.ts (the blazor.server.js entry) when its module-level 'started' flag is already true. The Server boot entry is single-shot: it configures circuit options, discovers server components, and starts the server in one pass; a second invocation is treated as a programmer error.

Source

Thrown at src/Components/Web.JS/src/Boot.Server.ts:19

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

import { Blazor } from './GlobalExports';
import { shouldAutoStart } from './BootCommon';
import { CircuitStartOptions, resolveOptions } from './Platform/Circuits/CircuitStartOptions';
import { setCircuitOptions, startServer } from './Boot.Server.Common';
import { ServerComponentDescriptor, discoverComponents } from './Services/ComponentDescriptorDiscovery';
import { DotNet } from '@microsoft/dotnet-js-interop';
import { InitialRootComponentsList } from './Services/InitialRootComponentsList';
import { JSEventRegistry } from './Services/JSEventRegistry';

type BlazorServerStartOptions = Partial<CircuitStartOptions> & { circuit?: Partial<CircuitStartOptions> };

let started = false;

function boot(userOptions?: BlazorServerStartOptions): Promise<void> {
  if (started) {
    throw new Error('Blazor has already started.');
  }
  started = true;

  // Accept the `circuit` property from the blazor.web.js options format
  const normalizedOptions = userOptions?.circuit ?? userOptions;
  const configuredOptions = resolveOptions(normalizedOptions);
  setCircuitOptions(Promise.resolve(configuredOptions || {}));

  const serverComponents = discoverComponents(document, 'server') as ServerComponentDescriptor[];
  const components = new InitialRootComponentsList(serverComponents);
  return startServer(components, JSEventRegistry.create(Blazor));
}

Blazor.start = boot;
window['DotNet'] = DotNet;

if (shouldAutoStart()) {
  boot();

View on GitHub (pinned to 294cab2f9b)

Solutions

1. Call Blazor.start() exactly once; remove the manual call if autostart is enabled, or disable autostart if you start manually.
2. Guard with a window-level flag (e.g. window.__blazorStarted) before invoking start.
3. Ensure the bundle is loaded once and not re-evaluated (avoid dynamic import() loops that re-import blazor.server.js).

Example fix

// before
<script src="blazor.server.js" autostart></script>
<script>Blazor.start({ ... });</script> <!-- throws -->

// after: pick one
<script src="blazor.server.js"></script>
<script>Blazor.start({ ... });</script>

function startServerBlazorOnce(opts?: any) {
  if ((window as any).__blazorServerStarted) return Promise.resolve();
  (window as any).__blazorServerStarted = true;
  return Blazor.start(opts);
}

function isServerBlazorStarted(): boolean {
  return !!(window as any).__blazorServerStarted;
}

try {
  await Blazor.start(opts);
} catch (e) {
  if (/already started/.test((e as Error).message)) return;
  throw e;
}

When it happens

Trigger: Calling Blazor.start() a second time after the Server bundle has already booted, or auto-start firing alongside a manual start().

Common situations: Page includes <script src="blazor.server.js" autostart> and a script also calls Blazor.start(); SPA framework re-importing the bundle; HMR reloading the module without resetting the flag.

Related errors

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

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