dotnet/runtime · error · Error

Failed to invoke 'onRuntimeConfigLoaded' on library initiali

Error message

Failed to invoke 'onRuntimeConfigLoaded' on library initializer '${name}': ${message}

What it means

callLibraryInitializerOnRuntimeConfigLoaded loads a JS library-initializer module and awaits its optional onRuntimeConfigLoaded(loaderConfig) hook inside try/catch. If that user-defined hook throws, the error is re-thrown with the module name and the original as cause. This fires for modules listed under resources.modulesAfterConfigLoaded.

Source

Thrown at src/native/libs/Common/JavaScript/loader/assets.ts:82

        if (!asset.resolvedUrl) throw new Error("Invalid config, resources is not set");
        mod = await import(/* webpackIgnore: true */ asset.resolvedUrl);
        asset.moduleExports = mod;
    }
    onDownloadedAsset(assetInternal);
    return mod;
}

export async function callLibraryInitializerOnRuntimeConfigLoaded(asset: JsAsset): Promise<any> {
    const module = await loadJSModule(asset);
    const name = asset.name || asset.resolvedUrl || "unknown";
    try {
        if (typeof module.onRuntimeConfigLoaded === "function") {
            await module.onRuntimeConfigLoaded(loaderConfig);
        }
        return module;
    } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        throw new Error(`Failed to invoke 'onRuntimeConfigLoaded' on library initializer '${name}': ${message}`, { cause: err });
    }
}

export async function callLibraryInitializerOnRuntimeReady([asset, modulePromise]: [JsAsset, Promise<any>]): Promise<void> {
    const module = await modulePromise;
    const name = asset.name || asset.resolvedUrl || "unknown";
    try {
        if (typeof module.onRuntimeReady === "function") {
            await module.onRuntimeReady(dotnetApi);
        }
    } catch (err) {
        const message = err instanceof Error ? err.message : String(err);
        throw new Error(`Failed to invoke 'onRuntimeReady' on library initializer '${name}': ${message}`, { cause: err });
    }
}

export function fetchMainWasm(asset: WasmAsset): Promise<Response> {
    totalAssetsToDownload++;

View on GitHub (pinned to 290d5ab72c)

Solutions

Read the '${name}' and '${message}' in the error to identify which initializer module and which line/logic failed.
Open that module's onRuntimeConfigLoaded implementation and fix the throw (guard the missing field, or fix the bug).
If the initializer is from a NuGet package, upgrade or downgrade the package to match the runtime version.
Temporarily remove the initializer entry from modulesAfterConfigLoaded to isolate whether the runtime starts without it.

Example fix

// before — initializer throws on missing config
export function onRuntimeConfigLoaded(cfg) {
  doSetup(cfg.extensions.myFeature.key); // throws if undefined
}

// after — guard the field
export function onRuntimeConfigLoaded(cfg) {
  const key = cfg.extensions?.myFeature?.key;
  if (!key) { console.warn('myFeature not configured'); return; }
  doSetup(key);
}

Defensive patterns

Strategy: try-catch

Type guard

// Narrow a module that exports the hook safely
function hasOnConfigLoaded(m: any): m is { onRuntimeConfigLoaded: (cfg: any) => void | Promise<void> } {
  return typeof m?.onRuntimeConfigLoaded === 'function';
}

Try / catch

try {
  await callLibraryInitializerOnRuntimeConfigLoaded(asset);
} catch (err) {
  // err.cause is the original initializer error
  console.error('Initializer failed:', asset.name, err.cause ?? err);
  // decide: skip this initializer or fail startup
}

Prevention

Wrap your onRuntimeConfigLoaded body in its own try/catch and degrade gracefully.
Validate cfg fields you read with optional chaining before use.
Pin the package version of any library that ships an initializer.

When it happens

Trigger: A library initializer module (registered via modulesAfterConfigLoaded in the boot config) exports an onRuntimeConfigLoaded function that throws synchronously or rejects asynchronously. The hook receives the mutable loaderConfig object.

Common situations: A Blazor/.NET library initializer that reads a config field that is missing; an initializer expecting a specific runtime version; a bug in the initializer's config validation; an initializer that calls a DOM API unavailable in the current host (e.g. Node).

Related errors

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