dotnet/runtime · error · Error

Expected runtimeOptions to be an array of strings

Error message

Expected runtimeOptions to be an array of strings

What it means

Thrown by mono_wasm_set_runtime_options when the options argument fails Array.isArray. The runtime-options setter expects an array of strings (each forwarded to mono_wasm_parse_runtime_options); any non-array (object, string, number, null, undefined) is rejected before allocation.

Source

Thrown at src/mono/browser/runtime/startup.ts:381

                mono_log_error("onDotnetReady () failed", err);
                throw err;
            }
        }
    } catch (err: any) {
        mono_log_error("mono_wasm_after_user_runtime_initialized () failed", err);
        throw err;
    }
}

// Set environment variable NAME to VALUE
// Should be called before mono_load_runtime_and_bcl () in most cases
export function mono_wasm_setenv (name: string, value: string): void {
    cwraps.mono_wasm_setenv(name, value);
}

export function mono_wasm_set_runtime_options (options: string[]): void {
    if (!Array.isArray(options))
        throw new Error("Expected runtimeOptions to be an array of strings");

    const argv = malloc(options.length * 4);
    let aindex = 0;
    for (let i = 0; i < options.length; ++i) {
        const option = options[i];
        if (typeof (option) !== "string")
            throw new Error("Expected runtimeOptions to be an array of strings");
        Module.setValue(<any>argv + (aindex * 4), cwraps.mono_wasm_strdup(option), "i32");
        aindex += 1;
    }
    cwraps.mono_wasm_parse_runtime_options(options.length, argv);
}

async function instantiate_wasm_module (
    imports: WebAssembly.Imports,
    successCallback: InstantiateWasmSuccessCallback,
): Promise<void> {
    // this is called so early that even Module exports like addRunDependency don't exist yet

View on GitHub (pinned to 60108ba66e)

Solutions

1. Always pass a string array: mono_wasm_set_runtime_options(['--gcserver', '--tiered']).
2. If your options may be a single string, wrap it: Array.isArray(opts) ? opts : opts ? [opts] : [].
3. Set config.runtimeOptions as an array in the runtime config object consumed by start_runtime.

Example fix

// before
mono_wasm_set_runtime_options('--gcserver');
// after
mono_wasm_set_runtime_options(['--gcserver']);

function setRuntimeOptionsSafe(opts: unknown) {
  const arr = Array.isArray(opts) ? opts : opts == null ? [] : [opts];
  mono_wasm_set_runtime_options(arr.filter((o): o is string => typeof o === 'string'));
}

function isStringArray(a: unknown): a is string[] {
  return Array.isArray(a) && a.every(o => typeof o === 'string');
}

When it happens

Trigger: Calling mono_wasm_set_runtime_options('--gcserver') (a single string), mono_wasm_set_runtime_options(null), or passing an options object instead of an array. The check on line 380-381 fires immediately.

Common situations: Passing a single CLI-style string instead of ['--gcserver']; passing the raw config.runtimeOptions when it is undefined or an object; migrating from an API that accepted a comma-separated string.

Related errors

• capacity >= 1
• value must be an address in the managed heap
• count_or_values must be either an array or a number greater
• Expected environment variable '${k}' to be a string but it w
• Expected string argument, got ${typeof(string)}

AI-assisted analysis of dotnet/runtime@60108ba66e (2026-08-10). Data as JSON: /api/errors/f65f52c10f723e03. Report an issue: GitHub.