dotnet/runtime · critical · Error

.NET runtime has failed to start, because too much memory…

Error message

.NET runtime has failed to start, because too much memory was requested. Please decrease the memory by adjusting EmccMaximumHeapSize.

What it means

Thrown by initializeModules() when the Emscripten factory promise rejects with an error whose message contains 'out of memory' (case-insensitive). This means the WASM linear memory requested during instantiation exceeds what the browser/engine can or will allocate. The .NET runtime wraps this to point the developer at EmccMaximumHeapSize, the build-time knob that caps the maximum heap. It is a fatal startup failure.

Solutions

Reduce the application's memory footprint: trim loaded assemblies, use lazy assembly loading (RuntimeOptions / Trimming), and reduce ICU data (use invariant globalization).
If you control the native build, decrease EmccMaximumHeapSize (or ALLOW_MEMORY_GROWTH cap) in the emscripten linker flags when rebuilding dotnet.wasm.
Enable server-side AOT or trimming to produce a smaller WASM binary and lower initial memory.
Test on a device with more memory or close other tabs; if it works, the issue is transient device pressure rather than a configuration defect.
Consider using diagnosticTracing or the browser's memory profiler to identify what is consuming the heap.

Example fix

// If using the managed build pipeline, set in your project file:
<!-- before -->
<PropertyGroup>
  <EmccMaximumHeapSize>4294967296</EmccMaximumHeapSize>
</PropertyGroup>

<!-- after (reduce to 2GB) -->
<PropertyGroup>
  <EmccMaximumHeapSize>2147483648</EmccMaximumHeapSize>
</PropertyGroup>

// Or reduce runtime memory with invariant globalization:
const runtime = await dotnet
  .withApplicationArguments()
  .withConfig({ globalizationMode: 'invariant' })
  .create();

Defensive patterns

Strategy: fallback

Validate before calling

// Check available memory before creating runtime
// Browsers expose deviceMemory (approximate); use as a heuristic
if ((navigator as any).deviceMemory && (navigator as any).deviceMemory < 2) {
  // load a lighter configuration
  dotnet.withConfig({ globalizationMode: 'invariant' });
}

Try / catch

try {
  await dotnet.create();
} catch (e) {
  if (e.message.includes('too much memory')) {
    // retry with lighter config
    await dotnet
      .withConfig({ globalizationMode: 'invariant' })
      .create();
  } else {
    throw e;
  }
}

Prevention

Use invariant globalization to reduce ICU data memory footprint.
Enable assembly trimming and lazy loading to reduce initial memory.
Test memory limits on low-end devices during development.
Monitor navigator.deviceMemory and adapt configuration accordingly.

When it happens

Trigger: The .NET WASM binary's configured INITIAL_MEMORY or MAXIMUM_MEMORY exceeds the browser's allocation limit (typically ~2GB for 32-bit WASM, or the device's available memory). Triggers on Module instantiation in createEmscriptenMain(), particularly on low-memory mobile devices, in memory-constrained tab discard scenarios, or with a custom build that raised EmccMaximumHeapSize too high.

Common situations: Loading a heavy .NET app on a mobile browser or an older device. Running multiple WASM instances in the same page. Custom-rebuilding the runtime with a larger MAXIMUM_MEMORY. Browser memory pressure from other tabs. Safari's stricter WASM memory limits.

Related errors

AI-assisted analysis of dotnet/runtime@60108ba66e (2026-08-10). Data as JSON: /api/errors/e99b8b88d7d6e765. Report an issue: GitHub.

Appendix: source

Thrown at src/mono/browser/runtime/loader/run.ts:393

    if (diagnosticModule) {
        diagnosticModule.setRuntimeGlobals(globalObjectsRoot);
    }

    await configureRuntimeStartup(emscriptenModule);
    loaderHelpers.runtimeModuleLoaded.promise_control.resolve();

    const result = emscriptenFactory((/*originalModule: EmscriptenModuleInternal*/) => {
        Object.assign(emscriptenModule, {
            __dotnet_runtime: {
                initializeReplacements, configureEmscriptenStartup, configureWorkerStartup, passEmscriptenInternals
            }
        });

        return emscriptenModule;
    });
    result.catch((error) => {
        if (error.message && error.message.toLowerCase().includes("out of memory")) {
            throw new Error(".NET runtime has failed to start, because too much memory was requested. Please decrease the memory by adjusting EmccMaximumHeapSize.");
        }
        throw error;
    });
}

async function downloadOnly ():Promise<void> {
    prepareEmscripten(emscriptenModule);

    // download config
    await mono_wasm_load_config(emscriptenModule);

    prepareAssets();

    init_globalization();

    mono_download_assets(); // intentionally not awaited

    await loaderHelpers.allDownloadsFinished.promise;

View on GitHub (pinned to 60108ba66e)