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

Thrown by loadLazyAssembly when the requested assembly name does not match any entry in the configured lazyAssembly resources list. It means lazy loading IS configured for the app, but the specific assembly you asked for was not declared as lazy-loadable.

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 290d5ab72c)

Solutions

1. Add the specific assembly to <BlazorWebAssemblyLazyLoad Include="AssemblyName.dll" /> in the project.
2. Verify the name passed to LoadAssembliesAsync exactly matches the declared assembly (case-sensitive, with or without .dll extension is handled, but the base name must match).
3. Re-publish so blazor.boot.json lists the assembly under lazyAssembly.
4. If the assembly must be available at startup, do not lazy-load it — load it eagerly instead.

Example fix

<!-- before: missing the specific assembly -->
<ItemGroup>
  <BlazorWebAssemblyLazyLoad Include="PluginA.dll" />
</ItemGroup>
<!-- code calls LoadAssembliesAsync(new[]{ "PluginB.dll" }) -->

<!-- after -->
<ItemGroup>
  <BlazorWebAssemblyLazyLoad Include="PluginA.dll" />
  <BlazorWebAssemblyLazyLoad Include="PluginB.dll" />
</ItemGroup>

const lazyNames = (config.resources?.lazyAssembly || []).map(a => a.virtualPath);
const wanted = 'PluginB.dll';
if (!lazyNames.includes(wanted)) {
  // add <BlazorWebAssemblyLazyLoad Include="PluginB.dll" />
}

function isLazyLoadable(config: any, assemblyName: string): boolean {
  const base = assemblyName.replace(/\.(dll|wasm)$/, '');
  return (config?.resources?.lazyAssembly || []).some(a =>
    a.virtualPath === base + '.dll' || a.virtualPath === base + '.wasm');
}

When it happens

Trigger: Produced when loadLazyAssembly(assemblyNameToLoad) finds no matching virtualPath (.dll or .wasm) in resources.lazyAssembly. E.g. requesting 'PluginB.dll' when only 'PluginA.dll' is declared.

Common situations: The assembly was added to the project but not marked with BlazorWebAssemblyLazyLoad; typo in the assembly name passed to LoadAssembliesAsync; the assembly is already loaded eagerly (so it was never added to the lazy list) but code tries to lazy-load it anyway.

Related errors

• No assemblies have been marked as lazy-loadable. Use the 'Bl
• No assemblies have been marked as lazy-loadable. Use the 'Bl
• ${assemblyNameToLoad} must be marked with 'BlazorWebAssembly
• Unexpected behavior ${asset.behavior} of asset ${asset.name}
• Missing window to the query parameters from

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