{"record":{"id":"81ff9254803af1da","repo":"dotnet/aspnetcore","slug":"the-runtime-must-be-loaded-before-it-gets-configur","errorCode":null,"errorMessage":"The runtime must be loaded before it gets configured.","messagePattern":"The runtime must be loaded before it gets configured\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/Components/Web.JS/src/Platform/Mono/MonoPlatform.ts","lineNumber":221,"sourceCode":"  const anyDotnet = (dotnet as any);\n  anyDotnet.withModuleConfig(moduleConfig);\n\n  if (options.configureRuntime) {\n    options.configureRuntime(dotnet);\n  }\n  if (justDownload) {\n    await dotnet.download(true);\n  } else {\n    runtime = await dotnet.create();\n  }\n}\n\nasync function configureRuntimeInstance(): Promise<PlatformApi> {\n  if (!runtime) {\n    runtime = await dotnet.create();\n  }\n  if (!runtime) {\n    throw new Error('The runtime must be loaded before it gets configured.');\n  }\n\n  const { setModuleImports, INTERNAL: mono_internal, getConfig, invokeLibraryInitializers } = runtime;\n  MONO_INTERNAL = mono_internal;\n  isMonoRuntime = typeof MONO_INTERNAL.monoStringToStringUnsafe === 'function';\n\n  attachDebuggerHotkey(getConfig());\n\n  Blazor.runtime = runtime;\n  Blazor._internal.dotNetCriticalError = printErr;\n  setModuleImports('blazor-internal', {\n    Blazor: { _internal: Blazor._internal },\n  });\n  const exports = await runtime.getAssemblyExports('Microsoft.AspNetCore.Components.WebAssembly');\n  Object.assign(Blazor._internal, {\n    dotNetExports: {\n      ...exports.Microsoft.AspNetCore.Components.WebAssembly.Services.DefaultWebAssemblyJSRuntime,\n    },","sourceCodeStart":203,"sourceCodeEnd":239,"githubUrl":"https://github.com/dotnet/aspnetcore/blob/3600ca084e9c8b5f4174fc5e747f4c52d2100806/src/Components/Web.JS/src/Platform/Mono/MonoPlatform.ts#L203-L239","documentation":"`configureRuntimeInstance` prepares the loaded .NET WASM runtime for use (binding internals, attaching imports, debugger hotkey). It first ensures a `runtime` exists by calling `dotnet.create()`; if creation still yields nothing, configuration cannot proceed and it throws. The runtime module must be successfully loaded and instantiated before configuration.","triggerScenarios":"`dotnet.create()` returns null/undefined, the runtime global failed to initialize, or `configureRuntimeInstance` is called before `importDotnetJs`/`instantiateModule` populated the `dotnet` module.","commonSituations":"A corrupted or partially downloaded `dotnet.js`/`dotnet.wasm`; a custom `loadBootResource` returning a bad runtime URL that loads a non-runtime script; build/CDN mismatch where the wrong `dotnet.js` is served; a bundler/CSP blocking the runtime module so `create()` fails.","solutions":["Verify the served `dotnet.js` and `dotnet.{wasm,blazor}` match your Blazor version and are not truncated.","Ensure CSP (`script-src`/`connect-src`) permits loading the runtime module and WASM.","If overriding runtime URLs via `loadBootResource`, point `dotnetjs` at a valid runtime JS module.","Clear browser cache / verify CDN integrity and redeploy matching assets."],"exampleFix":null,"handlingStrategy":"validation","validationCode":"if (!window.WebAssembly || !window.WebAssembly.validate) { /* handled by err 35 */ }\n// ensure dotnet.js is reachable and CSP allows it before start\nfetch('_framework/dotnet.js', { method: 'HEAD' }).then(r => console.log('runtime reachable:', r.ok));","typeGuard":null,"tryCatchPattern":"try { await Blazor.start(); }\ncatch (e) { if (/runtime must be loaded/.test(e.message)) { showRetryOrReload(); return; } throw e; }","preventionTips":["Verify dotnet.js and dotnet.wasm match your Blazor version and are not truncated.","Allow the runtime module in CSP script-src/connect-src.","If overriding URLs via loadBootResource, point dotnetjs at a valid module.","Clear cache and redeploy matching assets on mismatch."],"tags":["webassembly","blazor-wasm","runtime","startup","cdn"],"backgroundTag":null,"analyzedSha":"3600ca084e9c8b5f4174fc5e747f4c52d2100806","analyzedAt":"2026-08-11T16:32:30.678Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}