dotnet/efcore · error · OperationException

Could not load assembly

Error message

Could not load assembly '{assembly}'. Ensure it is referenced by the startup project '{startupProject}'.

What it means

OperationExecutor.Assembly is a lazy property that loads the target assembly by name. If Assembly.Load throws (FileNotFoundException, FileLoadException, BadImageFormatException, etc.), EF wraps it as a user-facing OperationException explaining that the assembly must be referenced by the startup project's output. The original exception is preserved as InnerException for diagnostics.

Solutions

Ensure the startup project has a project or assembly reference to the target assembly.
Build the startup project (dotnet build) so all referenced assemblies are present in the output.
Verify the assembly name spelling (it is the simple name, not a path).
If multi-targeting, ensure EF tools resolve the same TFM as the built output.

Example fix

# before: startup project doesn't reference the data project
# fix: add the reference
dotnet add src/MyApp/MyApp.csproj reference src/MyApp.Data/MyApp.Data.csproj

Defensive patterns

Strategy: try-catch

Validate before calling

try { var asm = Assembly.Load(new AssemblyName(targetAssemblyName)); }
catch (Exception ex) { /* report that the startup project must reference it */ throw; }

Try / catch

try { var executor = new OperationExecutor(...); }
catch (OperationException ex) when (ex.Message.StartsWith("Could not load assembly"))
{ /* add project reference and rebuild */ }

Prevention

Make the startup project reference the target/data project.
Build before running EF tools.
Keep assembly names stable; avoid renames without updating references.

When it happens

Trigger: OperationExecutor tries to Assembly.Load(new AssemblyName(_targetAssemblyName)) and the runtime cannot resolve it. This is the bootstrap step before any DbContext discovery, so it fires very early in any dotnet ef / PMC command.

Common situations: The target project references the assembly only at design time but it isn't an output dependency; the assembly name was mistyped or the project was renamed; multi-targeting produced a different output path; the startup project doesn't transitively reference the target; the assembly failed to build so its DLL is missing.

Related errors

AI-assisted analysis of dotnet/efcore@3a2006ef56 (2026-08-11). Data as JSON: /api/errors/1ed48596f5baee31. Report an issue: GitHub.

Appendix: source

Thrown at src/EFCore.Design/Design/OperationExecutor.cs:85

            && new SemanticVersionComparer().Compare(toolsVersion, runtimeVersion) < 0)
        {
            _reporter.WriteWarning(DesignStrings.VersionMismatch(toolsVersion, runtimeVersion));
        }
    }

    private Assembly Assembly
    {
        get
        {
            Assembly Create()
            {
                try
                {
                    return Assembly.Load(new AssemblyName(_targetAssemblyName));
                }
                catch (Exception ex)
                {
                    throw new OperationException(
                        DesignStrings.UnreferencedAssembly(_targetAssemblyName, _startupTargetAssemblyName),
                        ex);
                }
            }

            return field ??= Create();
        }
    }

    private Assembly StartupAssembly
        => field
            ??= Assembly.Load(new AssemblyName(_startupTargetAssemblyName));

    /// <summary>
    ///     Exposes the underlying operations for testing.
    /// </summary>
    [EntityFrameworkInternal]
    public virtual MigrationsOperations MigrationsOperations

View on GitHub (pinned to 3a2006ef56)