dotnet/runtime · error · Error

Loader configuration error: 'resources.coreAssembly' is requ

Error message

Loader configuration error: 'resources.coreAssembly' is required and must contain at least one assembly.

What it means

The second guard in validateLoaderConfig(): loaderConfig.resources must exist, must have a coreAssembly array, and that array must contain at least one entry. coreAssembly holds the assemblies required to bring up CoreCLR itself. Without them the runtime cannot initialize, so the loader fails fast.

Source

Thrown at src/native/libs/Common/JavaScript/loader/config.ts:18

// Licensed to the .NET Foundation under one or more agreements.
// The .NET Foundation licenses this file to you under the MIT license.

import type { Assets, LoaderConfig, LoaderConfigInternal } from "./types";
import { browserVirtualAppBase } from "./per-module";

export const loaderConfig: LoaderConfigInternal = {};

export function getLoaderConfig(): LoaderConfig {
    return loaderConfig;
}

export function validateLoaderConfig(): void {
    if (!loaderConfig.mainAssemblyName) {
        throw new Error("Loader configuration error: 'mainAssemblyName' is required.");
    }
    if (!loaderConfig.resources || !loaderConfig.resources.coreAssembly || loaderConfig.resources.coreAssembly.length === 0) {
        throw new Error("Loader configuration error: 'resources.coreAssembly' is required and must contain at least one assembly.");
    }
}

export function mergeLoaderConfig(source: Partial<LoaderConfigInternal>): void {
    defaultConfig(loaderConfig);
    normalizeConfig(source);
    mergeConfigs(loaderConfig, source);
}

function mergeConfigs(target: LoaderConfigInternal, source: Partial<LoaderConfigInternal>): LoaderConfigInternal {
    // no need to merge the same object
    if (target === source || source === undefined || source === null) return target;

    // Merge collections: target values first, then source values appended/spread on top.
    mergeResources(target.resources!, source.resources!);
    // For scalar fields with defaults, prefer source when defined, otherwise keep target default.
    // We patch source so that Object.assign below copies the correct resolved value.
    source.appendElementOnExit = source.appendElementOnExit !== undefined ? source.appendElementOnExit : target.appendElementOnExit;

View on GitHub (pinned to 290d5ab72c)

Solutions

1. Regenerate the boot config by republishing the project (dotnet publish) so resources.coreAssembly is populated.
2. If constructing config manually, ensure resources.coreAssembly is a non-empty array of assembly assets.
3. Verify the boot config JSON actually loaded — check network tab for the config file and that mergeLoaderConfig received parsed JSON, not undefined.
4. Confirm no later withConfig() call overwrote resources with an object lacking coreAssembly.

Example fix

// before
builder.withConfig({ mainAssemblyName: 'App', resources: { coreAssembly: [] } });

// after
builder.withConfig({
  mainAssemblyName: 'App',
  resources: { coreAssembly: [{ name: 'System.Runtime.dll', hash: '...' }] }
});

function validateResources(cfg: any) {
  const core = cfg?.resources?.coreAssembly;
  if (!Array.isArray(core) || core.length === 0) {
    throw new Error('Boot config missing resources.coreAssembly — republish.');
  }
}
validateResources(getLoaderConfig());

function hasCoreAssemblies(r: any): r is { coreAssembly: unknown[] } {
  return Array.isArray(r?.coreAssembly) && r.coreAssembly.length > 0;
}

When it happens

Trigger: Calling create()/download()/runMain() when resources is undefined, when resources.coreAssembly is undefined/null, or when resources.coreAssembly is an empty array. Typically a malformed or missing boot config.

Common situations: A custom publish profile that strips core assemblies; loading a partial config via withConfig() that omits resources.coreAssembly; the .bin or .json boot config file failed to download/parse so resources came through as empty; hand-rolling LoaderConfig in tests.

Related errors

• Loader configuration error: 'mainAssemblyName' is required.
• Invalid config, resources is not set
• Unexpected behavior ${asset.behavior} of asset ${asset.name}
• Missing window to the query parameters from
• URLSearchParams is supported

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