dotnet/runtime · error · Error

Can't use moduleFactory callback of createDotnetRuntime func

Error message

Can't use moduleFactory callback of createDotnetRuntime function.

What it means

Thrown by prepareEmscripten when the moduleFactory argument passed to createDotnetRuntime is neither a function nor a plain object. The runtime accepts only those two shapes for configuring the Emscripten module; anything else is a usage error.

Source

Thrown at src/mono/browser/runtime/loader/run.ts:308

    emscriptenPrepared = true;
    if (ENVIRONMENT_IS_WEB && loaderHelpers.config.forwardConsole && typeof globalThis.WebSocket != "undefined") {
        setup_proxy_console("main", globalThis.console, globalThis.location.origin);
    }
    mono_assert(emscriptenModule, "Null moduleConfig");
    mono_assert(loaderHelpers.config, "Null moduleConfig.config");

    // extract ModuleConfig
    if (typeof moduleFactory === "function") {
        const extension = moduleFactory(globalObjectsRoot.api) as any;
        if (extension.ready) {
            throw new Error("Module.ready couldn't be redefined.");
        }
        Object.assign(emscriptenModule, extension);
        deep_merge_module(emscriptenModule, extension);
    } else if (typeof moduleFactory === "object") {
        deep_merge_module(emscriptenModule, moduleFactory);
    } else {
        throw new Error("Can't use moduleFactory callback of createDotnetRuntime function.");
    }

    await detect_features_and_polyfill(emscriptenModule);
}

export async function createEmscripten (moduleFactory: DotnetModuleConfig | ((api: RuntimeAPI) => DotnetModuleConfig)): Promise<RuntimeAPI | EmscriptenModuleInternal> {
    await prepareEmscripten(moduleFactory);

    if (BuildConfiguration === "Debug" && !ENVIRONMENT_IS_WORKER) {
        mono_log_info(`starting script ${loaderHelpers.scriptUrl}`);
        mono_log_info(`starting in ${loaderHelpers.scriptDirectory}`);
    }
    if (loaderHelpers.config.exitOnUnhandledError) {
        installUnhandledErrorHandler();
    }

    registerEmscriptenExitHandlers();

View on GitHub (pinned to 290d5ab72c)

Solutions

1. Pass either a plain DotnetModuleConfig object or a (api) => DotnetModuleConfig function as the moduleFactory argument.
2. If you have nothing to configure, pass an empty object: createDotnetRuntime({}).
3. Double-check the createDotnetRuntime signature in your version of the runtime to ensure you pass the factory in the correct position.

Example fix

// before: wrong argument type
// createDotnetRuntime('./config.json'); // string is invalid
// createDotnetRuntime(); // undefined

// after: pass an object or a factory function
await createDotnetRuntime({ config: monoConfig });
// or
await createDotnetRuntime(api => ({ config: monoConfig }));

function isModuleFactory(arg: any): boolean {
  return typeof arg === 'function' || (typeof arg === 'object' && arg !== null && !Array.isArray(arg));
}
if (!isModuleFactory(arg)) { /* pass {} or a (api)=>config function */ }

function isModuleFactory(arg: unknown): arg is ((api: any) => any) | object {
  return typeof arg === 'function' || (typeof arg === 'object' && arg !== null && !Array.isArray(arg));
}

When it happens

Trigger: Produced when createDotnetRuntime is invoked with an argument of the wrong type — e.g. a string, a number, null (when not specially handled), an array, or undefined passed where a config/factory is expected.

Common situations: Passing the config in the wrong argument position; passing a module namespace/Proxy that typeof reports as something other than 'function' or 'object'; passing undefined by mistake; using an incompatible API wrapper.

Related errors

• Module.ready couldn't be redefined.
• Unexpected behavior ${asset.behavior} of asset ${asset.name}
• Missing window to the query parameters from
• URLSearchParams is supported
• Loader configuration error: 'mainAssemblyName' is required.

AI-assisted analysis of dotnet/runtime@290d5ab72c (2026-08-06). Data as JSON: /api/errors/c607e1fec8e13c54. Report an issue: GitHub.