dotnet/aspnetcore · error · Error

Cannot start the circuit until Blazor Server has started.

Error message

Cannot start the circuit until Blazor Server has started.

What it means

Thrown by startCircuit in Boot.Server.Common when serverStartPromise is undefined — i.e. startServer has never been called in this page. A SignalR circuit can only be established after the Server boot path has resolved its initializers and configuration, so attempting to start a circuit before that is rejected rather than silently waiting forever.

Solutions

1. Ensure Blazor.start() has resolved before invoking any reconnect/circuit API; await the start promise.
2. If autostart is disabled, sequence your code so start runs first and reconnect logic only afterwards.
3. Check the framework's started state (or guard with your own flag) before calling reconnect.
4. Investigate HMR/module re-evaluation that may have cleared serverStartPromise.

Example fix

// before
Blazor._internal.forceReconnect(); // fires startCircuit before boot

// after
await Blazor.start();
// ... later, after a disconnect event
Blazor.reconnect();

// Ensure start has run before reconnecting the circuit.
async function safeReconnect() {
  await Blazor.start();
  return Blazor.reconnect();
}

try {
  Blazor.reconnect();
} catch (e) {
  if (/Cannot start the circuit until Blazor Server has started/.test(e.message)) {
    await Blazor.start();
    Blazor.reconnect();
  } else throw e;
}

When it happens

Trigger: Calling Blazor.reconnect() or otherwise triggering startCircuit before Blazor.start()/startServer has run. Also seen when autostart is disabled and application code initiates a reconnect too early.

Common situations: Disabling autostart and then calling reconnect before start; HMR swapping out the boot module state so serverStartPromise is reset; race where a network-drop handler fires before initial boot completes.

Related errors

• Blazor has already started.
• Blazor Server has already started.
• Cannot start a disposed circuit.
• Circuit host not initialized.
• Circuit options have already been configured.

AI-assisted analysis of dotnet/aspnetcore@3600ca084e (2026-08-11). Data as JSON: /api/errors/a67942530197054a. Report an issue: GitHub.

Appendix: source

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

  }

  const cleanup = () => {
    circuit.sendDisconnectBeacon();
  };

  Blazor.disconnect = cleanup;

  window.addEventListener('pagehide', cleanup, { capture: false, once: true });

  logger.log(LogLevel.Information, 'Blazor server-side application started.');

  jsInitializer.invokeAfterStartedCallbacks(Blazor);
  resolve();
}

export async function startCircuit(): Promise<boolean> {
  if (!serverStartPromise) {
    throw new Error('Cannot start the circuit until Blazor Server has started.');
  }

  if (circuit && !circuit.isDisposedOrDisposing()) {
    return true;
  }

  // We might be starting a circuit already, if that's the case, we can just wait for that
  // to finish.
  if (circuitStarting) {
    return await circuitStarting;
  }

  await serverStartPromise;

  if (circuit && circuit.didRenderingFail()) {
    // We can't start a new circuit after a rendering failure because the renderer
    // might be in an invalid state.
    return false;

View on GitHub (pinned to 3600ca084e)