dotnet/runtime · error · Error

must be marked with 'BlazorWebAssemblyLazyLoad' item group…

Error message

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

What it means

Thrown by loadLazyAssembly in lazyLoading.ts when the requested assembly is not present in resources.lazyAssembly (no asset.virtualPath matches assemblyNameToLoad.dll/.wasm). The assembly was not opted into lazy loading via the BlazorWebAssemblyLazyLoad item group, so it is unavailable for on-demand load even though some other assemblies are.

Solutions

Add the exact assembly name to <BlazorWebAssemblyLazyLoad Include="Plugin.dll" /> and rebuild.
Pass the assembly name exactly as it appears in blazor.boot.json (with or without .dll per the API).
If the assembly is already eagerly loaded, do not call the lazy-load API for it.

Example fix

<!-- before: <BlazorWebAssemblyLazyLoad Include="Other.dll" /> -->
<!-- after: -->
<ItemGroup>
  <BlazorWebAssemblyLazyLoad Include="Plugin.dll" />
</ItemGroup>

Defensive patterns

Strategy: validation

Validate before calling

// before calling loadLazyAssembly(name)
const known = (config.resources?.lazyAssembly ?? []).map(a => a.virtualPath);
if (!known.includes(name.endsWith('.dll') ? name : name + '.dll'))
    throw new Error(`${name} is not in BlazorWebAssemblyLazyLoad`);

Prevention

Match the exact assembly name (including casing) in both the item group and the API call.
Do not lazy-load assemblies that are already eagerly referenced.
Rebuild after editing the BlazorWebAssemblyLazyLoad list.

When it happens

Trigger: Calling loadLazyAssembly('Plugin.dll') when Plugin.dll is referenced normally (loaded eagerly) but not listed as lazy-loadable; typo in the assembly name passed to the API; the assembly was renamed without updating the caller.

Common situations: Forgetting to add the specific assembly to <BlazorWebAssemblyLazyLoad Include=...>; referencing the assembly directly (so it is eagerly loaded) but still trying to lazy-load it; case mismatch in the dll name.

Related errors

AI-assisted analysis of dotnet/runtime@60108ba66e (2026-08-10). Data as JSON: /api/errors/6d2443ca88702e6d. Report an issue: GitHub.

Appendix: source

Thrown at src/mono/browser/runtime/lazyLoading.ts:36

        assemblyNameWithoutExtension = assemblyNameToLoad.substring(0, assemblyNameToLoad.length - 4);
    else if (assemblyNameToLoad.endsWith(".wasm"))
        assemblyNameWithoutExtension = assemblyNameToLoad.substring(0, assemblyNameToLoad.length - 5);

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

    let dllAsset: (AssemblyAsset & AssetEntryInternal) | null = null;
    for (let i = 0; i < lazyAssemblies.length; i++) {
        const asset = lazyAssemblies[i];
        if (asset.virtualPath === assemblyNameToLoadDll || asset.virtualPath === assemblyNameToLoadWasm) {
            dllAsset = asset as AssemblyAsset & AssetEntryInternal;
            dllAsset.behavior = "assembly";
            break;
        }
    }

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

    if (loaderHelpers.loadedAssemblies.includes(dllAsset.name)) {
        return false;
    }

    const pdbNameToLoad = assemblyNameWithoutExtension + ".pdb";
    let shouldLoadPdb = false;
    let pdbAsset: (PdbAsset & AssetEntryInternal) | null = null;
    if (loaderHelpers.config.debugLevel != 0 && loaderHelpers.isDebuggingSupported()) {
        for (let i = 0; i < lazyAssemblies.length; i++) {
            if (lazyAssemblies[i].virtualPath === pdbNameToLoad) {
                shouldLoadPdb = true;
                pdbAsset = lazyAssemblies[i] as PdbAsset & AssetEntryInternal;
                pdbAsset.behavior = "pdb";
                break;
            }
        }

View on GitHub (pinned to 60108ba66e)