dotnet/runtime · critical · Error

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

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 during runtime startup in initializeModules when the emscripten WASM module factory rejects with a message containing 'out of memory'. The runtime re-wraps it to point at the EmccMaximumHeapSize MSBuild property, which maps to emscripten's -s MAXIMUM_MEMORY flag (default 2147483648 = 2GiB per browser.proj / BrowserWasmApp.CoreCLR.targets). The browser refused to allocate or grow the linear memory to the requested size.

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 290d5ab72c)

Solutions

Lower EmccMaximumHeapSize, e.g. dotnet publish -p:EmccMaximumHeapSize=1073741824 (1GiB), and republish.
Also reduce EmccInitialHeapSize so the up-front allocation fits the target device.
Test on the lowest-end target device; many mobile browsers cap WASM memory around 1-2GiB.
Profile real heap usage and trim working set; if you legitimately need >2GiB, a browser target may be wrong.

Example fix

// before
dotnet publish -p:EmccMaximumHeapSize=4294967296
// after
dotnet publish -p:EmccMaximumHeapSize=1073741824 -p:EmccInitialHeapSize=67108864

Defensive patterns

Strategy: validation

Validate before calling

// Before invoking the runtime, sanity-check the configured heap against the host.
const configuredMaxBytes = config.maxMemoryBytes; // whatever your build/publish set
// browsers vary; a conservative mobile cap
const conservativeCap = 1024 * 1024 * 1024; // 1GiB
if (configuredMaxBytes && configuredMaxBytes > conservativeCap) {
  console.warn('EmccMaximumHeapSize may exceed this device\'s WASM limit; consider lowering it.');
}

Try / catch

// Wrap the runtime create/configure promise; the re-wrapped error points at EmccMaximumHeapSize.
try {
  await dotnet.create();
} catch (e) {
  if (String(e?.message).toLowerCase().includes('emmccmaximumheapsize')) {
    // surface a user-facing message and offer to retry with a smaller heap build
  }
  throw e;
}

Prevention

Keep EmccMaximumHeapSize at or below the default 2GiB; raise it only after testing on the lowest-end target device.
Test startup in private/incognito mode and on mobile, where WASM memory caps are lower.
Set EmccInitialHeapSize modestly so the first allocation is likely to succeed.

When it happens

Trigger: Publishing/running the wasm app with /p:EmccMaximumHeapSize (or EmccInitialHeapSize) set larger than the host browser will grant; loading in an environment with a low WASM memory cap. The catch in initializeModules matches the lowercased 'out of memory' substring from the emscripten factory error.

Common situations: Cranking EmccMaximumHeapSize to 4GiB for a memory-heavy app and then running on iOS Safari, a 32-bit browser, a low-RAM mobile device, or a private/incognito window; setting the initial heap beyond the device limit; memory pressure from other tabs.

Related errors

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