{"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/60108ba66eb7d1d12f595480091b4ad80a24b172/src/mono/browser/runtime/loader/run.ts#L375-L411","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","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."],"exampleFix":"// If using the managed build pipeline, set in your project file:\n<!-- before -->\n<PropertyGroup>\n  <EmccMaximumHeapSize>4294967296</EmccMaximumHeapSize>\n</PropertyGroup>\n\n<!-- after (reduce to 2GB) -->\n<PropertyGroup>\n  <EmccMaximumHeapSize>2147483648</EmccMaximumHeapSize>\n</PropertyGroup>\n\n// Or reduce runtime memory with invariant globalization:\nconst runtime = await dotnet\n  .withApplicationArguments()\n  .withConfig({ globalizationMode: 'invariant' })\n  .create();","handlingStrategy":"fallback","validationCode":"// Check available memory before creating runtime\n// Browsers expose deviceMemory (approximate); use as a heuristic\nif ((navigator as any).deviceMemory && (navigator as any).deviceMemory < 2) {\n  // load a lighter configuration\n  dotnet.withConfig({ globalizationMode: 'invariant' });\n}","typeGuard":null,"tryCatchPattern":"try {\n  await dotnet.create();\n} catch (e) {\n  if (e.message.includes('too much memory')) {\n    // retry with lighter config\n    await dotnet\n      .withConfig({ globalizationMode: 'invariant' })\n      .create();\n  } else {\n    throw e;\n  }\n}","preventionTips":["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."],"tags":["memory","startup","wasm","emscripten","mobile"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}