{"record":{"id":"e6bc42d1f4a35812","repo":"dotnet/runtime","slug":"failed-to-invoke-onruntimeready-on-library-initi","errorCode":null,"errorMessage":"Failed to invoke 'onRuntimeReady' on library initializer '${name}': ${message}","messagePattern":"Failed to invoke 'onRuntimeReady' on library initializer '(.+?)': (.+?)","errorType":"exception","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/native/libs/Common/JavaScript/loader/assets.ts","lineNumber":95,"sourceCode":"            await module.onRuntimeConfigLoaded(loaderConfig);\n        }\n        return module;\n    } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        throw new Error(`Failed to invoke 'onRuntimeConfigLoaded' on library initializer '${name}': ${message}`, { cause: err });\n    }\n}\n\nexport async function callLibraryInitializerOnRuntimeReady([asset, modulePromise]: [JsAsset, Promise<any>]): Promise<void> {\n    const module = await modulePromise;\n    const name = asset.name || asset.resolvedUrl || \"unknown\";\n    try {\n        if (typeof module.onRuntimeReady === \"function\") {\n            await module.onRuntimeReady(dotnetApi);\n        }\n    } catch (err) {\n        const message = err instanceof Error ? err.message : String(err);\n        throw new Error(`Failed to invoke 'onRuntimeReady' on library initializer '${name}': ${message}`, { cause: err });\n    }\n}\n\nexport function fetchMainWasm(asset: WasmAsset): Promise<Response> {\n    totalAssetsToDownload++;\n    const assetInternal = asset as AssetEntryInternal;\n    if (assetInternal.name && !asset.resolvedUrl) {\n        asset.resolvedUrl = locateFile(assetInternal.name);\n    }\n    assetInternal.behavior = \"dotnetwasm\";\n    if (!asset.resolvedUrl) throw new Error(\"Invalid config, resources is not set\");\n    mainWasmAsset = asset;\n    wasmBinaryPromise = loadResource(assetInternal);\n    return wasmBinaryPromise;\n}\n\nexport async function instantiateMainWasm(imports: WebAssembly.Imports, successCallback: InstantiateWasmSuccessCallback): Promise<void> {\n    const assetInternal = mainWasmAsset as AssetEntryInternal;","sourceCodeStart":77,"sourceCodeEnd":113,"githubUrl":"https://github.com/dotnet/runtime/blob/60108ba66eb7d1d12f595480091b4ad80a24b172/src/native/libs/Common/JavaScript/loader/assets.ts#L77-L113","documentation":"Thrown by callLibraryInitializerOnRuntimeReady() (src/native/libs/Common/JavaScript/loader/assets.ts:86). After the runtime is ready, the loader invokes each module's onRuntimeReady(dotnetApi) hook; if the hook throws or rejects, the catch at line 93 wraps the original error and re-throws, tagging it with the initializer's name.","triggerScenarios":"A module listed in resources.modulesAfterRuntimeReady exports onRuntimeReady; the loader calls it with the runtime API; if it throws synchronously or returns a rejected promise, the error is wrapped and rethrown.","commonSituations":"A library initializer that uses dotnetApi incorrectly against the deployed runtime version; an initializer that fails to register a JS export the managed side expects; a bug in the onRuntimeReady body; a missing dependency the initializer needs at runtime-ready time.","solutions":["Read error.cause to find the underlying failure in the named initializer and fix it.","Test the initializer against the exact runtime version it will run under.","Register all JS exports the initializer needs before onRuntimeReady runs."],"exampleFix":"// before: initializer calls an API that does not exist yet\nexport function onRuntimeReady(api) {\n  api.setHeapLock(true); // TypeError -> 'Failed to invoke onRuntimeReady'\n}\n\n// after\nexport function onRuntimeReady(api) {\n  if (typeof api.setHeapLock === 'function') api.setHeapLock(true);\n}","handlingStrategy":"try-catch","validationCode":"async function safeReadyHook(mod: any, api: any): Promise<void> {\n  if (typeof mod?.onRuntimeReady === 'function') {\n    await mod.onRuntimeReady(api);\n  }\n}","typeGuard":"function hasOnRuntimeReady(m: any): m is { onRuntimeReady: (api: any) => void | Promise<void> } {\n  return typeof m?.onRuntimeReady === 'function';\n}","tryCatchPattern":"try {\n  await callLibraryInitializerOnRuntimeReady([asset, modulePromise]);\n} catch (err) {\n  // err.cause is the underlying initializer error\n  console.error('onRuntimeReady failed:', (err as Error).message, (err as any).cause);\n  throw err;\n}","preventionTips":["Register all JS exports an initializer needs before onRuntimeReady runs.","Feature-detect dotnetApi methods before calling them in the initializer.","Test the initializer against the runtime version it will ship with."],"tags":["library-initializer","runtime-api","extension-point"],"backgroundTag":null,"analyzedSha":"60108ba66eb7d1d12f595480091b4ad80a24b172","analyzedAt":"2026-08-10T18:54:11.478Z","contentChangedAt":null,"schemaVersion":2},"datasetVersion":"2026-09-23T08:17:48.524Z"}