{"record":{"id":"e99b8b88d7d6e765","repo":"dotnet/runtime","slug":"net-runtime-has-failed-to-start-because-too-much","errorCode":null,"errorMessage":".NET runtime has failed to start, because too much memory was requested. Please decrease the memory by adjusting EmccMaximumHeapSize.","messagePattern":"\\.NET runtime has failed to start, because too much memory was requested\\. Please decrease the memory by adjusting EmccMaximumHeapSize\\.","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"critical","filePath":"src/mono/browser/runtime/loader/run.ts","lineNumber":393,"sourceCode":"    if (diagnosticModule) {\n        diagnosticModule.setRuntimeGlobals(globalObjectsRoot);\n    }\n\n    await configureRuntimeStartup(emscriptenModule);\n    loaderHelpers.runtimeModuleLoaded.promise_control.resolve();\n\n    const result = emscriptenFactory((/*originalModule: EmscriptenModuleInternal*/) => {\n        Object.assign(emscriptenModule, {\n            __dotnet_runtime: {\n                initializeReplacements, configureEmscriptenStartup, configureWorkerStartup, passEmscriptenInternals\n            }\n        });\n\n        return emscriptenModule;\n    });\n    result.catch((error) => {\n        if (error.message && error.message.toLowerCase().includes(\"out of memory\")) {\n            throw new Error(\".NET runtime has failed to start, because too much memory was requested. Please decrease the memory by adjusting EmccMaximumHeapSize.\");\n        }\n        throw error;\n    });\n}\n\nasync function downloadOnly ():Promise<void> {\n    prepareEmscripten(emscriptenModule);\n\n    // download config\n    await mono_wasm_load_config(emscriptenModule);\n\n    prepareAssets();\n\n    init_globalization();\n\n    mono_download_assets(); // intentionally not awaited\n\n    await loaderHelpers.allDownloadsFinished.promise;","sourceCodeStart":375,"sourceCodeEnd":411,"githubUrl":"https://github.com/dotnet/runtime/blob/290d5ab72cc1102813fbc0406fb186ceadabc340/src/mono/browser/runtime/loader/run.ts#L375-L411","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// before\ndotnet publish -p:EmccMaximumHeapSize=4294967296\n// after\ndotnet publish -p:EmccMaximumHeapSize=1073741824 -p:EmccInitialHeapSize=67108864","handlingStrategy":"validation","validationCode":"// Before invoking the runtime, sanity-check the configured heap against the host.\nconst configuredMaxBytes = config.maxMemoryBytes; // whatever your build/publish set\n// browsers vary; a conservative mobile cap\nconst conservativeCap = 1024 * 1024 * 1024; // 1GiB\nif (configuredMaxBytes && configuredMaxBytes > conservativeCap) {\n  console.warn('EmccMaximumHeapSize may exceed this device\\'s WASM limit; consider lowering it.');\n}","typeGuard":null,"tryCatchPattern":"// Wrap the runtime create/configure promise; the re-wrapped error points at EmccMaximumHeapSize.\ntry {\n  await dotnet.create();\n} catch (e) {\n  if (String(e?.message).toLowerCase().includes('emmccmaximumheapsize')) {\n    // surface a user-facing message and offer to retry with a smaller heap build\n  }\n  throw e;\n}","preventionTips":["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."],"tags":["wasm","memory","startup","configuration","emscripten"],"analyzedSha":"290d5ab72cc1102813fbc0406fb186ceadabc340","analyzedAt":"2026-08-06T19:57:01.276Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}