dotnet/efcore · critical · OperationException

Could not load assembly '{assembly}'. Ensure it is reference

Error message

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

What it means

OperationExecutor.Assembly tried Assembly.Load on the target assembly name (the --project / startup-project assembly) and the load threw. The assembly isn't reachable from the application's load context. The inner exception holds the real loader error (FileNotFoundException, BadImageFormatException, etc.).

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 dbf9771522)

Solutions

Build the project first: dotnet build, then re-run dotnet ef.
Add a project reference from the startup project to the target project.
Verify the --project / --startup-project paths and that the resulting assembly names are correct.
Match target frameworks across projects (don't load a net8.0 assembly into a net48 process or vice versa where unsupported).

Example fix

// before
dotnet ef migrations add Init   // project never built
// after
dotnet build
dotnet ef migrations add Init

Defensive patterns

Strategy: try-catch

Validate before calling

try { Assembly.Load(new AssemblyName(targetAssemblyName)); }
catch (Exception ex) { throw new InvalidOperationException($"Build the project or add a reference; cannot load '{targetAssemblyName}'.", ex); }

Type guard

static bool IsLoadable(string asmName) { try { _ = Assembly.Load(new AssemblyName(asmName)); return true; } catch { return false; } }

Try / catch

try { /* dotnet ef invocation */ }
catch (OperationException ex) when (ex.Message.Contains("Could not load assembly"))
{ /* run dotnet build, verify --project path, then retry */ }

Prevention

Always 'dotnet build' before 'dotnet ef'.
Reference target projects from the startup project.
Keep target frameworks aligned across projects.

When it happens

Trigger: dotnet ef is invoked with a --project or --startup-project whose output assembly is missing or unloadable. Assembly.Load(new AssemblyName(_targetAssemblyName)) throws at line 81, wrapped at line 85.

Common situations: Project not built (no DLL in bin/); wrong assembly name passed; target framework mismatch producing a BadImageFormatException; assembly lives in a path not on the probing path; the startup project doesn't reference the target project.

Related errors

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