AvaloniaUI/Avalonia · error · InvalidOperationException

Assembly {name} needs to be referenced and explicitly loaded

Error message

Assembly {name} needs to be referenced and explicitly loaded before loading resources

What it means

Thrown by AssemblyDescriptorResolver when an assembly name is requested for resource loading but is not already loaded into the AppDomain, AND the runtime does not support dynamic code (RuntimeFeature.IsDynamicCodeSupported is false, i.e. NativeAOT/trimmed scenarios). In such runtimes Assembly.Load is illegal, so the resolver cannot dynamically load the assembly and instead throws this InvalidOperationException instructing the caller to reference and explicitly load the assembly beforehand.

Source

Thrown at src/Avalonia.Base/Platform/Internal/AssemblyDescriptorResolver.cs:39

    public IAssemblyDescriptor GetAssembly(string name)
    {
        if (name == null)
            throw new ArgumentNullException(nameof(name));

        if (!_assemblyNameCache.TryGetValue(name, out var rv))
        {
            var loadedAssemblies = AppDomain.CurrentDomain.GetAssemblies();
            var match = loadedAssemblies.FirstOrDefault(a => name.Equals(a.GetName().Name, StringComparison.InvariantCultureIgnoreCase));
            if (match != null)
            {
                _assemblyNameCache[name] = rv = new AssemblyDescriptor(match);
            }
            else
            {
#if NET6_0_OR_GREATER
                if (!RuntimeFeature.IsDynamicCodeSupported)
                {
                    throw new InvalidOperationException(
                        $"Assembly {name} needs to be referenced and explicitly loaded before loading resources");
                }
#endif
                name = Uri.UnescapeDataString(name);
                _assemblyNameCache[name] = rv = new AssemblyDescriptor(Assembly.Load(name));
            }
        }

        return rv;
    }
    public void InvalidateAssemblyCache(string name)
    {
        _assemblyNameCache.Remove(name);
    }

    public void InvalidateAssemblyCache()
    {
        _assemblyNameCache.Clear();

View on GitHub (pinned to 11c5427268)

Solutions

1. Explicitly load the assembly before requesting its resources: call Assembly.Load or reference a type from it (e.g. typeof(SomeType).Assembly) early at startup to force the loader.
2. Ensure the assembly is listed as a true reference so the NativeAOT/trim graph includes it.
3. Pre-load all resource assemblies during app startup initialization before any asset resolution occurs.
4. If possible, embed resources in the main assembly to avoid cross-assembly dynamic loading.

Example fix

// before (NativeAOT): resource requested from NotYetLoaded.dll throws

// after
// Force-load the assembly at startup before resource access:
_ = typeof(MyLibrary.MarkerType).Assembly; // roots the assembly reference
// or explicitly: Assembly.Load("MyLibrary");

static void EnsureAssemblyLoaded(string name)
{
    var loaded = AppDomain.CurrentDomain.GetAssemblies();
    if (!loaded.Any(a => name.Equals(a.GetName().Name, StringComparison.OrdinalIgnoreCase)))
        throw new InvalidOperationException($"Pre-load assembly '{name}' before requesting resources.");
}

try { return resolver.Resolve(name); }
catch (InvalidOperationException ex) when (ex.Message.Contains("explicitly loaded"))
{ /* force-load the assembly then retry */ }

When it happens

Trigger: On a NativeAOT or trimmed deployment (RuntimeFeature.IsDynamicCodeSupported == false), requesting resources from an assembly that is referenced but not yet loaded into the current AppDomain. The cache lookup fails and, because dynamic loading is unavailable, the resolver throws rather than attempting Assembly.Load.

Common situations: Avalonia apps published as NativeAOT or with trimming enabled, where a resource (e.g. an asset, style, or font) is requested from an assembly that is loaded lazily or only via reflection; multi-project setups where the resource assembly is a dependency not explicitly loaded at startup; plugins/assemblies loaded on demand.

Related errors

• owner
• The Style already has a parent.
• Resources
• Duration value cannot be negative.
• DelayBetweenIterations value cannot be negative.

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/57c6bc10aabd216b. Report an issue: GitHub.