dotnet/runtime · error · Error

${assemblyNameToLoad} must be marked with 'BlazorWebAssembly

Error message

${assemblyNameToLoad} must be marked with 'BlazorWebAssemblyLazyLoad' item group in your project file to allow lazy-loading.

What it means

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.

Source

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

    if (loadedLazyAssemblies.has(assemblyNameWithoutExtension)) {
        return false;
    }

    const assemblyNameToLoadDll = assemblyNameWithoutExtension + ".dll";
    const assemblyNameToLoadWasm = assemblyNameWithoutExtension + ".wasm";

    let dllAsset: AssemblyAsset | null = null;
    for (const asset of lazyAssemblies) {
        const fileName = lazyAssetFileName(asset.virtualPath);
        if (fileName === assemblyNameToLoadDll || fileName === assemblyNameToLoadWasm) {
            dllAsset = asset;
            break;
        }
    }

    if (!dllAsset) {
        throw new Error(`${assemblyNameToLoad} must be marked with 'BlazorWebAssemblyLazyLoad' item group in your project file to allow lazy-loading.`);
    }

    await fetchAssembly(dllAsset);
    loadedLazyAssemblies.add(assemblyNameWithoutExtension);

    if (loaderConfig.debugLevel !== 0) {
        const pdbNameToLoad = assemblyNameWithoutExtension + ".pdb";
        const pdbAssets = loaderConfig.resources?.pdb;
        let pdbAssetToLoad: AssemblyAsset | undefined;
        if (pdbAssets) {
            for (const pdbAsset of pdbAssets) {
                if (lazyAssetFileName(pdbAsset.virtualPath) === pdbNameToLoad) {
                    pdbAssetToLoad = pdbAsset;
                    break;
                }
            }
        }
        if (!pdbAssetToLoad) {

View on GitHub (pinned to 290d5ab72c)

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.

Example fix

<!-- before -->
<BlazorWebAssemblyLazyLoad Include="Bar" />

<!-- after -->
<BlazorWebAssemblyLazyLoad Include="Bar" />
<BlazorWebAssemblyLazyLoad Include="Foo" />

Defensive patterns

Strategy: type-guard

Validate before calling

const lazy = new Set((getLoaderConfig().resources?.lazyAssembly ?? []).map(a => a.virtualPath.split('/').pop()));
if (!lazy.has(`${assemblyNameWithoutExt}.dll`) && !lazy.has(`${assemblyNameWithoutExt}.wasm`)) {
  throw new Error(`${assemblyNameWithoutExt} not declared as lazy in <BlazorWebAssemblyLazyLoad>`);
}

Type guard

function isDeclaredLazy(name: string, cfg: any): boolean {
  const lazy = cfg?.resources?.lazyAssembly ?? [];
  return lazy.some(a => a?.virtualPath?.endsWith(`/${name}.dll`) || a?.virtualPath?.endsWith(`/${name}.wasm`) || a?.virtualPath === `${name}.dll`);
}

Try / catch

try { await loadLazyAssembly(name); }
catch (err) {
  if (/must be marked with 'BlazorWebAssemblyLazyLoad'/.test(err.message)) {
    // prompt user / log to add the item, or load eagerly
  } else throw err;
}

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

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