DEV Community

Cristian Sifuentes
Cristian Sifuentes

Posted on

EF Core Migrations Troubleshooting Guide — Design Package, Tooling Versions & Multi‑Project Setups

#csharp #efcore #dotnet #database

EF Core Migrations Troubleshooting Guide — Design Package, Tooling Versions & Multi‑Project Setups

EF Core Migrations Troubleshooting Guide — Design Package, Tooling Versions & Multi‑Project Setups

If you work with Entity Framework Core long enough, you’ll eventually hit the “migrations wall”:

  • “The contextual keyword 'var'…“? No.
  • “Cannot drop database because it is currently in use”? Sometimes.
  • But more often it’s one of these three classics:
  1. “Your startup project doesn’t reference Microsoft.EntityFrameworkCore.Design”
  2. “The Entity Framework tools version 9.0.5 is older than runtime 10.0.0”
  3. “Your target project TechNotes doesn’t match your migrations assembly TechNotes.Infrastructure”

The good news: these errors are 100% normal in real-world, multi-project solutions—and they’re also 100% fixable once you understand what EF Core is trying to tell you.

This post is a copy‑paste‑ready troubleshooting guide you can keep open in your terminal while you work.

Table of Contents

  1. Design‑Time Package Missing: Microsoft.EntityFrameworkCore.Design
  2. Tools vs Runtime Version Mismatch (9.0.x vs 10.0.0)
  3. Startup Project vs Migrations Project Mismatch
  4. Recommended CLI Commands for Multi‑Project Solutions
  5. Quick Checklists & Mental Models
  6. Final Thoughts & Upgrade Tips

1. Design‑Time Package Missing: Microsoft.EntityFrameworkCore.Design

The error

When you run something like:

dotnet ef migrations add CreateTableNotes
Enter fullscreen mode Exit fullscreen mode

…and see:

Your startup project 'TechNotes' doesn't reference Microsoft.EntityFrameworkCore.Design.

This package is required for the Entity Framework Core Tools to work.

This error is 100% normal when your startup project doesn’t have the design‑time package installed.

Even if you already have:

Microsoft.EntityFrameworkCore
Microsoft.EntityFrameworkCore.SqlServer
Microsoft.EntityFrameworkCore.Tools
Enter fullscreen mode Exit fullscreen mode

…you still need:

Microsoft.EntityFrameworkCore.Design
Enter fullscreen mode Exit fullscreen mode

⚠️ The key detail: this must be installed in your startup project, not just the project that contains your DbContext.

1.1 Fix — Install the missing package

From your startup project folder (for example, TechNotes):

dotnet add package Microsoft.EntityFrameworkCore.Design
Enter fullscreen mode Exit fullscreen mode

Or, if you want to pin a specific version that matches your EF Core runtime:

dotnet add package Microsoft.EntityFrameworkCore.Design --version 10.0.0
Enter fullscreen mode Exit fullscreen mode

(Use the version that matches your Microsoft.EntityFrameworkCore runtime.)

1.2 Make sure EF is using the right startup project

EF Core always uses the startup project to:

  • Build the app
  • Resolve configuration
  • Build the DbContext
  • Locate connection strings

Common structure:

TechNotes           (Web/API — Startup project)
TechNotes.Data      (DbContext, Entities, Repositories, etc.)
Enter fullscreen mode Exit fullscreen mode

In this case, the correct CLI call is:

dotnet ef migrations add CreateTableNotes   --startup-project ./TechNotes   --project ./TechNotes.Data
Enter fullscreen mode Exit fullscreen mode

Where:

  • --startup-project = where Program.cs / Main lives
  • --project = where your DbContext lives and where you want migrations generated

1.3 Restore & retry

After installing the package and wiring the projects correctly:

dotnet restore
dotnet ef migrations add CreateTableNotes
Enter fullscreen mode Exit fullscreen mode

If everything is wired correctly you’ll see:

Build succeeded.
Done. To undo this action, use 'dotnet ef migrations remove'.
Enter fullscreen mode Exit fullscreen mode

1.4 Why this package is required

Microsoft.EntityFrameworkCore.Design contains the design‑time infrastructure EF needs to work from the CLI:

  • Design‑time services
  • Scaffolding code
  • Migration generators
  • Tool entry points

Without this package, EF Core CLI cannot:

  • ✔ Create migrations
  • ✔ Apply migrations
  • ✔ Scaffold entities from a database
  • ✔ Run design‑time DbContextFactory implementations

If this error keeps coming back, double‑check that:

  • The package is installed in the startup project
  • The CLI is running from the correct folder or using the right --startup-project

2. Tools vs Runtime Version Mismatch (9.0.5 vs 10.0.0)

The next classic warning:

The Entity Framework tools version '9.0.5' is older than that of the runtime '10.0.0'.

Update the tools for the latest features and bug fixes.

Here’s what’s happening:

  • Your app is using EF Core runtime 10.0.0
  • Your EF Core CLI Tools (dotnet-ef) are still at 9.0.5
  • EF is warning you that migrations and scaffolding may behave incorrectly

While EF often tries to stay compatible, the safest setup is to keep tooling and runtime aligned.

2.1 Fix — Update EF Core Tools and Design to 10.0.0

From your startup project:

dotnet add package Microsoft.EntityFrameworkCore.Tools --version 10.0.0
dotnet add package Microsoft.EntityFrameworkCore.Design --version 10.0.0
Enter fullscreen mode Exit fullscreen mode

Then restore:

dotnet restore
Enter fullscreen mode Exit fullscreen mode

2.2 Verify your tools 

dotnet ef
Enter fullscreen mode Exit fullscreen mode

You should see something like:

Entity Framework Core .NET Command-line Tools 10.0.0
Enter fullscreen mode Exit fullscreen mode

Now rerun your migration:

dotnet ef migrations add CreateTableNotes
Enter fullscreen mode Exit fullscreen mode

With everything aligned, the version warning disappears and you avoid subtle bugs such as:

  • Broken migrations when new EF features appear
  • Wrong metadata or SQL being generated
  • Features that exist at runtime but are missing in your tooling

🧠 Rule of thumb: Runtime and Tools should be on the same major version. When you upgrade EF, treat Tools and Design as part of the same package family.

3. Startup Project vs Migrations Project Mismatch

Once the design package and tool versions are fixed, another message may appear:

Your target project 'TechNotes' doesn't match your migrations assembly 'TechNotes.Infrastructure'.

Either change your target project or change your migrations assembly.

EF is basically saying:

“The migrations I already know about live in TechNotes.Infrastructure, but you’re asking me to target TechNotes as the migrations project. Pick one.”

This is super common in Clean Architecture or multi-layered solutions where:

  • TechNotes = ASP.NET Core API (startup project)
  • TechNotes.Infrastructure = EF Core DbContext + repository implementations + migrations

To fix this, you must decide where migrations live and be consistent.

3.1 Quick mental model

  • Startup project = has Program.cs / Main and configures DI. Used to get configuration, connection strings, logging, etc.
  • Migrations project (target project) = the project where:
    • Your DbContext lives, and/or
    • You want the Migrations/ folder and generated .cs files

Right now, for example:

  • Startup project = TechNotes
  • Migrations assembly = TechNotes.Infrastructure

EF complains: Target project = TechNotes, Migrations Assembly = TechNotes.Infrastructure

→ “These don’t match.”

3.2 Option 1 (recommended): Keep migrations in TechNotes.Infrastructure

This works beautifully with Clean Architecture: infrastructure owns DbContext and migrations; API owns hosting and HTTP.

From your solution root:

dotnet ef migrations add CreateTableNotes   --project TechNotes.Infrastructure   --startup-project TechNotes
Enter fullscreen mode Exit fullscreen mode

Where:

  • --project 👉 where DbContext + migrations live (TechNotes.Infrastructure)
  • --startup-project 👉 where Program.cs / host lives (TechNotes)

Then, in TechNotes (startup) make sure DI is configured like this:

builder.Services.AddDbContext<AppDbContext>(options =>
    options.UseSqlServer(
        builder.Configuration.GetConnectionString("DefaultConnection"),
        b => b.MigrationsAssembly("TechNotes.Infrastructure")));
Enter fullscreen mode Exit fullscreen mode

Now all migrations will be generated into:

TechNotes.Infrastructure/Migrations
Enter fullscreen mode Exit fullscreen mode

…and the API will happily apply them at runtime.

3.3 Option 2: Move migrations to TechNotes (API project)

If you prefer to keep migrations in the API project itself:

  1. Configure EF so the migrations assembly is the API project: 
   builder.Services.AddDbContext<AppDbContext>(options =>
       options.UseSqlServer(
           builder.Configuration.GetConnectionString("DefaultConnection"),
           b => b.MigrationsAssembly("TechNotes")));
Enter fullscreen mode Exit fullscreen mode

  1. Delete any existing migrations from TechNotes.Infrastructure

    (The old folder, so EF doesn’t get confused.)

  2. From the TechNotes folder, run:

   dotnet ef migrations add CreateTableNotes
Enter fullscreen mode Exit fullscreen mode

Now migrations will live in:

TechNotes/Migrations
Enter fullscreen mode Exit fullscreen mode

and EF will stop complaining about mismatched assemblies.

4. Recommended CLI Commands for Multi‑Project Solutions

Here’s a small cheat sheet for the most common scenarios.

4.1 Add a migration (DbContext in Infrastructure, API as startup) 

dotnet ef migrations add <Name>   --project TechNotes.Infrastructure   --startup-project TechNotes
Enter fullscreen mode Exit fullscreen mode

4.2 List migrations 

dotnet ef migrations list   --project TechNotes.Infrastructure   --startup-project TechNotes
Enter fullscreen mode Exit fullscreen mode

4.3 Update database 

dotnet ef database update   --project TechNotes.Infrastructure   --startup-project TechNotes
Enter fullscreen mode Exit fullscreen mode

4.4 Remove last migration 

dotnet ef migrations remove   --project TechNotes.Infrastructure   --startup-project TechNotes
Enter fullscreen mode Exit fullscreen mode

Adapt project names and paths (./src/...) as needed for your solution.

5. Quick Checklists & Mental Models

5.1 Design‑time package checklist

  • [ ] Installed Microsoft.EntityFrameworkCore.Design in the startup project
  • [ ] Matching EF Core version (e.g., 10.0.0)
  • [ ] dotnet restore completes without errors
  • [ ] dotnet ef runs and prints the correct version

5.2 Tools vs runtime version checklist

  • [ ] Microsoft.EntityFrameworkCore = 10.0.0 (runtime)
  • [ ] Microsoft.EntityFrameworkCore.Tools = 10.0.0
  • [ ] Microsoft.EntityFrameworkCore.Design = 10.0.0
  • [ ] dotnet ef shows Tools 10.0.0

5.3 Startup vs migrations checklist

  • [ ] You know which project is the startup (Program.cs)
  • [ ] You know which project is the migrations project (DbContext, Migrations/)
  • [ ] CLI commands use --startup-project and --project consistently
  • [ ] UseSqlServer(..., b => b.MigrationsAssembly("Your.Migrations.Assembly")) is set correctly
  • [ ] dotnet ef migrations list runs without “target project doesn’t match migrations assembly” errors

6. Final Thoughts & Upgrade Tips

Entity Framework Core can feel picky, especially when you:

  • Use Clean Architecture (multiple projects, Infrastructure/Domain/API)
  • Upgrade between major versions (9 → 10)
  • Split contexts and migrations across different assemblies

But once you internalize a few mental models, the errors stop being mysterious and start being useful diagnostics:

  • “Design package missing” → install Microsoft.EntityFrameworkCore.Design in your startup.
  • “Tools older than runtime” → align Tools + Design + runtime versions.
  • “Target project vs migrations assembly mismatch” → decide where migrations live and keep CLI + DI config in sync.

If you’re still stuck after this:

  • Print your src/ folder tree
  • Paste the EF‑related part of Program.cs
  • Paste your *.csproj with EF dependencies

…and treat it like a small architecture review. You’ll very likely find a mismatch between:

  • Project references
  • Package versions
  • CLI arguments

Once those three are aligned, EF Core migrations become boring again—and that’s exactly what you want in production.

✍️ Written by: Cristian Sifuentes — .NET / EF Core / Clean Architecture enthusiast.

If this saved you from another midnight “why won’t migrations run?” session, feel free to bookmark it or turn it into your team’s internal EF Core checklist.

Top comments (0)