{"record":{"id":"aedbdf4e2f4329b2","repo":"dotnet/runtime","slug":"assemblynametoload-must-be-marked-with-blazorw-aedbdf","errorCode":null,"errorMessage":"${assemblyNameToLoad} must be marked with 'BlazorWebAssemblyLazyLoad' item group in your project file to allow lazy-loading.","messagePattern":"(.+?) must be marked with 'BlazorWebAssemblyLazyLoad' item group in your project file to allow lazy-loading\\.","errorType":"validation","errorClass":"Error","httpStatus":null,"severity":"error","filePath":"src/native/libs/Common/JavaScript/loader/assets.ts","lineNumber":297,"sourceCode":"\n    if (loadedLazyAssemblies.has(assemblyNameWithoutExtension)) {\n        return false;\n    }\n\n    const assemblyNameToLoadDll = assemblyNameWithoutExtension + \".dll\";\n    const assemblyNameToLoadWasm = assemblyNameWithoutExtension + \".wasm\";\n\n    let dllAsset: AssemblyAsset | null = null;\n    for (const asset of lazyAssemblies) {\n        const fileName = lazyAssetFileName(asset.virtualPath);\n        if (fileName === assemblyNameToLoadDll || fileName === assemblyNameToLoadWasm) {\n            dllAsset = asset;\n            break;\n        }\n    }\n\n    if (!dllAsset) {\n        throw new Error(`${assemblyNameToLoad} must be marked with 'BlazorWebAssemblyLazyLoad' item group in your project file to allow lazy-loading.`);\n    }\n\n    await fetchAssembly(dllAsset);\n    loadedLazyAssemblies.add(assemblyNameWithoutExtension);\n\n    if (loaderConfig.debugLevel !== 0) {\n        const pdbNameToLoad = assemblyNameWithoutExtension + \".pdb\";\n        const pdbAssets = loaderConfig.resources?.pdb;\n        let pdbAssetToLoad: AssemblyAsset | undefined;\n        if (pdbAssets) {\n            for (const pdbAsset of pdbAssets) {\n                if (lazyAssetFileName(pdbAsset.virtualPath) === pdbNameToLoad) {\n                    pdbAssetToLoad = pdbAsset;\n                    break;\n                }\n            }\n        }\n        if (!pdbAssetToLoad) {","sourceCodeStart":279,"sourceCodeEnd":315,"githubUrl":"https://github.com/dotnet/runtime/blob/290d5ab72cc1102813fbc0406fb186ceadabc340/src/native/libs/Common/JavaScript/loader/assets.ts#L279-L315","documentation":"fetchLazyAssembly iterates resources.lazyAssembly looking for an asset whose filename matches assemblyNameToLoad (with .dll or .wasm extension). If no match is found, it throws naming the requested assembly and instructing to mark it with <BlazorWebAssemblyLazyLoad>. This guards against lazy-requesting an assembly that was published as eager.","triggerScenarios":"Runtime requests lazy load of 'Foo' but resources.lazyAssembly contains only 'Bar'. The requested assembly was either not declared as lazy, or declared under a different name/casing.","commonSituations":"Forgetting to add the assembly to <BlazorWebAssemblyLazyLoad>; name mismatch (requesting 'foo.dll' vs declared 'Foo.dll'); assembly was previously lazy but the item got removed; trying to lazy-load a framework assembly that must be eager.","solutions":["Add <BlazorWebAssemblyLazyLoad Include=\"Foo\" /> to the .csproj and republish.","Match the casing and extension exactly — pass either 'Foo' or 'Foo.dll' to the lazy-load API; the loader strips/normalizes extensions but the base name must equal the declared one.","Inspect blazor.boot.json lazyAssembly array to see exactly which names are declared lazy.","If the assembly must stay eager, remove the runtime call that lazy-loads it."],"exampleFix":"<!-- before -->\n<BlazorWebAssemblyLazyLoad Include=\"Bar\" />\n\n<!-- after -->\n<BlazorWebAssemblyLazyLoad Include=\"Bar\" />\n<BlazorWebAssemblyLazyLoad Include=\"Foo\" />","handlingStrategy":"type-guard","validationCode":"const lazy = new Set((getLoaderConfig().resources?.lazyAssembly ?? []).map(a => a.virtualPath.split('/').pop()));\nif (!lazy.has(`${assemblyNameWithoutExt}.dll`) && !lazy.has(`${assemblyNameWithoutExt}.wasm`)) {\n  throw new Error(`${assemblyNameWithoutExt} not declared as lazy in <BlazorWebAssemblyLazyLoad>`);\n}","typeGuard":"function isDeclaredLazy(name: string, cfg: any): boolean {\n  const lazy = cfg?.resources?.lazyAssembly ?? [];\n  return lazy.some(a => a?.virtualPath?.endsWith(`/${name}.dll`) || a?.virtualPath?.endsWith(`/${name}.wasm`) || a?.virtualPath === `${name}.dll`);\n}","tryCatchPattern":"try { await loadLazyAssembly(name); }\ncatch (err) {\n  if (/must be marked with 'BlazorWebAssemblyLazyLoad'/.test(err.message)) {\n    // prompt user / log to add the item, or load eagerly\n  } else throw err;\n}","preventionTips":["Keep a single source-of-truth list of lazy assemblies and cross-check it in CI.","Use exact casing when requesting lazy loads.","Inspect blazor.boot.json lazyAssembly after each publish."],"tags":["blazor","lazy-loading","config","assemblies"],"analyzedSha":"290d5ab72cc1102813fbc0406fb186ceadabc340","analyzedAt":"2026-08-06T19:57:01.276Z","schemaVersion":2},"datasetVersion":"2026-08-06T23:17:07.152Z"}