{"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/3600ca084e9c8b5f4174fc5e747f4c52d2100806/src/Components/Web.JS/src/Boot.Server.Common.ts#L9-L45","documentation":"Thrown by setCircuitOptions in Boot.Server.Common when the module-level 'options' variable is already set. setCircuitOptions is intended to run exactly once per Blazor Server boot; calling it again means the boot path executed twice, which would overwrite resolved CircuitStartOptions and leave the circuit in an inconsistent state.","triggerScenarios":"Invoking Blazor.start() (or the Boot.Server boot() entrypoint) more than once in the same page, or manually calling setCircuitOptions after the framework already did so. The second call hits the populated 'options' guard.","commonSituations":"A script tag calling Blazor.start() in addition to the auto-start logic; a SPA shell that re-initializes Blazor on navigation; bundler misconfiguration causing the boot module to be evaluated twice; mixing manual and automatic startup.","solutions":["Ensure Blazor.start() is called at most once per page load; remove duplicate invocation sites.","If you are unsure whether Blazor has started, guard with a flag or check Blazor's documented started state before calling start.","Disable autostart and call start exactly once yourself when you need explicit control.","Audit bundler/SVG-inlined script setup so the boot module is not imported twice."],"exampleFix":"// before — autostart plus a manual call\n<script autostart=\"true\" src=\"blazor.web.js\"></script>\n<script>Blazor.start({ ... });</script> // double start\n\n// after — disable autostart and start once\n<script src=\"blazor.web.js\" autostart=\"false\"></script>\n<script>Blazor.start({ ... });</script>","handlingStrategy":"validation","validationCode":"// Guard the start call so setCircuitOptions is invoked once.\nlet bootPromise;\nfunction ensureBlazorServerStarted(opts) {\n  return bootPromise ?? (bootPromise = Blazor.start(opts));\n}","typeGuard":null,"tryCatchPattern":"try {\n  await Blazor.start(opts);\n} catch (e) {\n  if (/already been configured|already started/.test(e.message)) {\n    // already booted — treat as success\n  } else throw e;\n}","preventionTips":["Set autostart=\"false\" whenever you call Blazor.start() manually.","Memoize the start promise at a single entrypoint.","Avoid calling Blazor.start() from multiple modules.","Audit bundler/HMR config to prevent double-evaluation of the boot module."],"tags":["blazor-server","boot","lifecycle","double-start"],"backgroundTag":null,"analyzedSha":"3600ca084e9c8b5f4174fc5e747f4c52d2100806","analyzedAt":"2026-08-11T16:32:30.678Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}