{"record":{"id":"527ca53ac2e2d946","repo":"dotnet/aspnetcore","slug":"circuit-options-have-already-been-configured","errorCode":null,"errorMessage":"Circuit options have already been configured.","messagePattern":"Circuit options have already been configured\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/Components/Web.JS/src/Boot.Server.Common.ts","lineNumber":27,"sourceCode":"import { DefaultReconnectionHandler } from './Platform/Circuits/DefaultReconnectionHandler';\nimport { discoverServerPersistedState, ServerComponentDescriptor } from './Services/ComponentDescriptorDiscovery';\nimport { JSEventRegistry } from './Services/JSEventRegistry';\nimport { fetchAndInvokeInitializers } from './JSInitializers/JSInitializers.Server';\nimport { RootComponentManager } from './Services/RootComponentManager';\nimport { WebRendererId } from './Rendering/WebRendererId';\nimport { addDispatchEventMiddleware } from './Rendering/WebRendererInteropMethods';\n\nlet initializersPromise: Promise<void> | undefined;\nlet appState: string;\nlet circuit: CircuitManager;\nlet options: CircuitStartOptions;\nlet logger: ConsoleLogger;\nlet serverStartPromise: Promise<void>;\nlet circuitStarting: Promise<boolean> | undefined;\n\nexport function setCircuitOptions(initializersReady: Promise<Partial<CircuitStartOptions>>) {\n  if (options) {\n    throw new Error('Circuit options have already been configured.');\n  }\n\n  initializersPromise = setOptions(initializersReady);\n\n  async function setOptions(initializers: Promise<Partial<CircuitStartOptions>>): Promise<void> {\n    const configuredOptions = await initializers;\n    options = resolveOptions(configuredOptions);\n  }\n}\n\nexport function startServer(components: RootComponentManager<ServerComponentDescriptor>, jsEventRegistry: JSEventRegistry): Promise<void> {\n  if (serverStartPromise !== undefined) {\n    throw new Error('Blazor Server has already started.');\n  }\n\n  serverStartPromise = new Promise(startServerCore.bind(null, components, jsEventRegistry));\n\n  return serverStartPromise;","sourceCodeStart":9,"sourceCodeEnd":45,"githubUrl":"https://github.com/dotnet/aspnetcore/blob/294cab2f9b2e03af6b953820c7ab497c3c8b7ad9/src/Components/Web.JS/src/Boot.Server.Common.ts#L9-L45","documentation":"Thrown by setCircuitOptions in Boot.Server.Common.ts if the module-level 'options' variable is already set. Circuit options are a singleton: they are configured once during boot and reused for the lifetime of the page. A second call means boot/initialization logic ran twice.","triggerScenarios":"Calling Blazor.start({ circuit: {...} }) more than once, or a JS initializer that also calls setCircuitOptions, or Boot.Web.ts's onInitialDomContentLoaded running twice (e.g. two DOMContentLoaded listeners or a double boot).","commonSituations":"Manually invoking Blazor.start() in script while auto-start is also enabled; an HMR/hot-reload cycle re-running the boot module; a custom hosting page that calls start() then re-imports the bundle; misconfigured initializers that mutate circuit options twice.","solutions":["Call Blazor.start() at most once; guard with if (!Blazor._internal.isStarted) or check hasStartedServer() before starting.","Disable auto-start (do not include the autostart flag / set window.Blazor to disable) when you call start() manually.","Ensure JS initializers only read options, not re-configure them; route all option changes through the single boot call.","Remove duplicate <script> references to blazor.server.js / blazor.web.js."],"exampleFix":"// before: double configuration\nBlazor.start({ circuit: { ... } });\nBlazor.start({ circuit: { ... } }); // throws\n\n// after: start once\nif (!window.__blazorStarted) {\n  window.__blazorStarted = true;\n  Blazor.start({ circuit: { ... } });\n}","handlingStrategy":"validation","validationCode":"// No public 'optionsConfigured' flag is exported; guard with a window flag.\nfunction configureCircuitOnce(opts: Partial<CircuitStartOptions>) {\n  if ((window as any).__circuitOptionsConfigured) return;\n  (window as any).__circuitOptionsConfigured = true;\n  Blazor.start({ circuit: opts });\n}","typeGuard":"declare module './Boot.Server.Common' {\n  function setCircuitOptions(p: Promise<Partial<CircuitStartOptions>>): void;\n}\n// call only when not yet started\nfunction shouldConfigure(): boolean {\n  return !(window as any).__circuitOptionsConfigured;\n}","tryCatchPattern":"try {\n  setCircuitOptions(initializersReady);\n} catch (e) {\n  if (/already been configured/.test((e as Error).message)) {\n    // idempotent no-op\n  } else throw e;\n}","preventionTips":["Call Blazor.start() exactly once per page load.","Disable autostart when starting manually.","Do not re-configure circuit options from JS initializers.","Track a window-level started flag in your boot script."],"tags":["blazor-server","startup","configuration","singleton"],"analyzedSha":"294cab2f9b2e03af6b953820c7ab497c3c8b7ad9","analyzedAt":"2026-08-06T20:08:02.189Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}