{"record":{"id":"3aef11c901306776","repo":"dotnet/runtime","slug":"address-must-be-a-location-in-the-native-heap","errorCode":null,"errorMessage":"address must be a location in the native heap","messagePattern":"address must be a location in the native heap","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/mono/browser/runtime/roots.ts","lineNumber":52,"sourceCode":"    const offset = malloc(capacityBytes);\n    if ((<any>offset % 4) !== 0)\n        throw new Error(\"Malloc returned an unaligned offset\");\n\n    _zero_region(offset, capacityBytes);\n\n    return new WasmRootBufferImpl(offset, capacity, true, name);\n}\n\n/**\n * Allocates a WasmRoot pointing to a root provided and controlled by external code. Typicaly on managed stack.\n * Releasing this root will not de-allocate the root space. You still need to call .release().\n */\nexport function mono_wasm_new_external_root<T extends MonoObject> (address: VoidPtr | MonoObjectRef): WasmRoot<T> {\n    if (WasmEnableThreads && runtimeHelpers.disableManagedTransition) throw new Error(\"External roots are not supported in multithreaded mode\");\n    let result: WasmExternalRoot<T>;\n\n    if (!address)\n        throw new Error(\"address must be a location in the native heap\");\n\n    if (_external_root_free_instances.length > 0) {\n        result = _external_root_free_instances.pop()!;\n        result._set_address(address);\n    } else {\n        result = new WasmExternalRoot<T>(address);\n    }\n\n    return result;\n}\n\n/**\n * Allocates temporary storage for a pointer into the managed heap.\n * Pointers stored here will be visible to the GC, ensuring that the object they point to aren't moved or collected.\n * If you already have a managed pointer you can pass it as an argument to initialize the temporary storage.\n * The result object has get() and set(value) methods, along with a .value property.\n * When you are done using the root you must call its .release() method.\n */","sourceCodeStart":34,"sourceCodeEnd":70,"githubUrl":"https://github.com/dotnet/runtime/blob/60108ba66eb7d1d12f595480091b4ad80a24b172/src/mono/browser/runtime/roots.ts#L34-L70","documentation":"Thrown by mono_wasm_new_external_root when the supplied address is falsy (0, null, undefined, or NaN-coerced-to-0). An external root must point at an existing location in the native heap; a null address has no slot for the runtime to register, so creation is rejected.","triggerScenarios":"Calling mono_wasm_new_external_root(0), mono_wasm_new_external_root(null), mono_wasm_new_external_root(undefined), or passing a pointer variable that was never assigned a real native-heap address.","commonSituations":"Using an uninitialized pointer field as the root address; passing a MonoObjectRef that was zeroed; logic that conditionally allocates a native slot but always calls the root API; off-by-one that yields address 0.","solutions":["Ensure the address argument is a real native-heap location (e.g. from malloc or a stack alloc) before calling the API.","Guard: skip external-root creation when the address is 0/null/undefined.","Debug-print the address source upstream to find where the zero value originates."],"exampleFix":"// before\nconst root = mono_wasm_new_external_root(maybeNullPtr);\n// after\nif (!maybeNullPtr) throw new Error('cannot create external root: slot not allocated');\nconst root = mono_wasm_new_external_root(maybeNullPtr);","handlingStrategy":"type-guard","validationCode":"function newExternalRootSafe(addr: VoidPtr | MonoObjectRef | null) {\n  if (!addr) throw new Error('slot not allocated');\n  return mono_wasm_new_external_root(addr);\n}","typeGuard":"function isNonNullAddress(a: unknown): a is number {\n  return typeof a === 'number' && a > 0;\n}","tryCatchPattern":null,"preventionTips":["Always allocate the native slot before wrapping it as an external root.","Treat a zero address from malloc/stack-alloc as a hard failure before reaching the root API.","Initialize pointer fields to a sentinel and assert non-zero at the call site."],"tags":["gc-roots","validation","argument-error","native-heap"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}