{"record":{"id":"8415245d0d2c07ad","repo":"dotnet/runtime","slug":"capacity-1","errorCode":null,"errorMessage":"capacity >= 1","messagePattern":"capacity >= 1","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/mono/browser/runtime/roots.ts","lineNumber":29,"sourceCode":"import { gc_locked } from \"./gc-lock\";\n\nconst maxScratchRoots = 8192;\nlet _scratch_root_buffer: WasmRootBuffer | null = null;\nlet _scratch_root_free_indices: Int32Array | null = null;\nlet _scratch_root_free_indices_count = 0;\nconst _scratch_root_free_instances: WasmRoot<any>[] = [];\nconst _external_root_free_instances: WasmExternalRoot<any>[] = [];\n\n/**\n * Allocates a block of memory that can safely contain pointers into the managed heap.\n * The result object has get(index) and set(index, value) methods that can be used to retrieve and store managed pointers.\n * Once you are done using the root buffer, you must call its release() method.\n * For small numbers of roots, it is preferable to use the mono_wasm_new_root and mono_wasm_new_roots APIs instead.\n */\nexport function mono_wasm_new_root_buffer (capacity: number, name?: string): WasmRootBuffer {\n    if (WasmEnableThreads && runtimeHelpers.disableManagedTransition) throw new Error(\"External roots are not supported when threads are enabled\");\n    if (capacity <= 0)\n        throw new Error(\"capacity >= 1\");\n\n    capacity = capacity | 0;\n\n    const capacityBytes = capacity * 4;\n    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> {","sourceCodeStart":11,"sourceCodeEnd":47,"githubUrl":"https://github.com/dotnet/runtime/blob/60108ba66eb7d1d12f595480091b4ad80a24b172/src/mono/browser/runtime/roots.ts#L11-L47","documentation":"Thrown by mono_wasm_new_root_buffer when the supplied capacity is zero or negative. A root buffer must hold at least one GC root slot, so any non-positive capacity is rejected before any allocation occurs. It is a pure argument-validation guard at the top of the factory.","triggerScenarios":"Calling mono_wasm_new_root_buffer(0), mono_wasm_new_root_buffer(-1), or passing a computed capacity that underflows to <= 0 (e.g. an array length of an empty input).","commonSituations":"Deriving capacity from a dynamic source such as args.length or an array size without clamping; off-by-one or off-by-zero when sizing a buffer from a count that is occasionally zero; passing an uninitialized/NaN number that coerces to 0.","solutions":["Guard the call: only allocate when the computed capacity is >= 1.","If a zero-capacity case is legitimate for your caller, return early / use a no-op object instead of calling the API.","Coerce with Math.max(1, capacity) only when at least one slot is genuinely required."],"exampleFix":"// before\nconst buf = mono_wasm_new_root_buffer(items.length); // throws when items is empty\n// after\nif (items.length > 0) {\n  const buf = mono_wasm_new_root_buffer(items.length);\n}","handlingStrategy":"validation","validationCode":"function safeRootBuffer(capacity: number) {\n  if (!Number.isInteger(capacity) || capacity < 1) return null;\n  return mono_wasm_new_root_buffer(capacity);\n}","typeGuard":"function isValidCapacity(c: unknown): c is number {\n  return typeof c === 'number' && Number.isInteger(c) && c >= 1;\n}","tryCatchPattern":null,"preventionTips":["Clamp capacity to at least 1 only when a slot is truly required.","Return early from callers when the input collection is empty rather than allocating zero.","Derive capacity from validated, non-empty sources."],"tags":["gc-roots","validation","argument-error","typescript"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-14T00:17:10.932Z"}