What causes "The runtime must be loaded before it gets configured." in dotnet/aspnetcore?

Verify the served `dotnet.js` and `dotnet.{wasm,blazor}` match your Blazor version and are not truncated.

dotnet/aspnetcore · critical · Error

The runtime must be loaded before it gets configured.

Error message

The runtime must be loaded before it gets configured.

What it means

`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.

Source

Thrown at src/Components/Web.JS/src/Platform/Mono/MonoPlatform.ts:221

  const anyDotnet = (dotnet as any);
  anyDotnet.withModuleConfig(moduleConfig);

  if (options.configureRuntime) {
    options.configureRuntime(dotnet);
  }
  if (justDownload) {
    await dotnet.download(true);
  } else {
    runtime = await dotnet.create();
  }
}

async function configureRuntimeInstance(): Promise<PlatformApi> {
  if (!runtime) {
    runtime = await dotnet.create();
  }
  if (!runtime) {
    throw new Error('The runtime must be loaded before it gets configured.');
  }

  const { setModuleImports, INTERNAL: mono_internal, getConfig, invokeLibraryInitializers } = runtime;
  MONO_INTERNAL = mono_internal;
  isMonoRuntime = typeof MONO_INTERNAL.monoStringToStringUnsafe === 'function';

  attachDebuggerHotkey(getConfig());

  Blazor.runtime = runtime;
  Blazor._internal.dotNetCriticalError = printErr;
  setModuleImports('blazor-internal', {
    Blazor: { _internal: Blazor._internal },
  });
  const exports = await runtime.getAssemblyExports('Microsoft.AspNetCore.Components.WebAssembly');
  Object.assign(Blazor._internal, {
    dotNetExports: {
      ...exports.Microsoft.AspNetCore.Components.WebAssembly.Services.DefaultWebAssemblyJSRuntime,
    },

View on GitHub (pinned to 3600ca084e)

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.

Defensive patterns

Strategy: validation

Validate before calling

if (!window.WebAssembly || !window.WebAssembly.validate) { /* handled by err 35 */ }
// ensure dotnet.js is reachable and CSP allows it before start
fetch('_framework/dotnet.js', { method: 'HEAD' }).then(r => console.log('runtime reachable:', r.ok));

Try / catch

try { await Blazor.start(); }
catch (e) { if (/runtime must be loaded/.test(e.message)) { showRetryOrReload(); return; } throw e; }

Prevention

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.

When it happens

Trigger: `dotnet.create()` returns null/undefined, the runtime global failed to initialize, or `configureRuntimeInstance` is called before `importDotnetJs`/`instantiateModule` populated the `dotnet` module.

Common situations: 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.

Related errors

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