DEV Community

Cristian Sifuentes
Cristian Sifuentes

Posted on

EF Core Migrations Pitfall — Resolving Version Mismatch Between Tools and Runtime in Fluent API Projects

#dotnet #backend #csharp #programming

EF Core Migrations Pitfall — Resolving Version Mismatch Between Tools and Runtime in Fluent API Projects

EF Core Migrations Pitfall — Resolving Version Mismatch Between Tools and Runtime in Fluent API Projects

Modern .NET development embraces clean architectures powered by Entity Framework Core. As we scale APIs using Fluent API configurations and code-first migrations, one crucial area to manage is tooling version alignment — especially when mixing preview and stable builds.

In this post, we’ll explore a real scenario where a developer runs:

dotnet ef migrations add InitialCreate
Enter fullscreen mode Exit fullscreen mode

Only to hit a runtime mismatch error:

System.MissingMethodException:
Method not found: 'IProperty IEntityType.FindDiscriminatorProperty()'
Enter fullscreen mode Exit fullscreen mode

❌ What Went Wrong?

This issue arises because the design-time tools (Microsoft.EntityFrameworkCore.Design) are at version 9.0.5, while the runtime (Microsoft.EntityFrameworkCore) is at 10.0.0-preview.4. These versions are not binary compatible.

EF Core’s dotnet ef tools depend on internal APIs that evolve across versions. This means even minor version mismatches can break migration scaffolding.

✅ The Fix

Option 1: Align versions

Update your Design package to match the runtime:

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

Option 2: Downgrade runtime

If you need stability, downgrade your runtime packages to 9.0.5 to match the tools:

dotnet add package Microsoft.EntityFrameworkCore.SqlServer --version 9.0.5
Enter fullscreen mode Exit fullscreen mode

When Using Fluent API — Version Matching Is Critical

If you're fully committed to Fluent API configuration, you’ll need migrations to evolve the schema. A mismatch in versions will break:

  • .AddMigration(...)
  • .UpdateDatabase(...)
  • Reverse engineering scaffolds (Scaffold-DbContext)

Sample DbContext 

protected override void OnModelCreating(ModelBuilder builder)
{
    builder.Entity<Job>(job =>
    {
        job.ToTable("Job");
        job.HasKey(j => j.JobId);
        job.Property(j => j.Title).IsRequired().HasMaxLength(200);
        job.Ignore(j => j.Resume);
    });
}
Enter fullscreen mode Exit fullscreen mode

This won’t work with broken dotnet ef scaffolding tools unless versioned properly.

Best Practices for EF Core Tooling and Fluent API Projects

Practice Benefit
Match tool/runtime versions Avoid runtime errors
Use preview features together Never mix stable + preview
Use dotnet ef --version to verify Prevent silent failures
Separate project for migrations Isolate preview risk from runtime
Document toolchain Help team upgrades and CI/CD

Final Thoughts

EF Core migrations are incredibly powerful — especially when used with Fluent API-first design. But that power comes with version sensitivity.

Always ensure that your Microsoft.EntityFrameworkCore.Design package matches your SqlServer, InMemory, and runtime packages exactly.

✍️ Written by: Cristian Sifuentes – Full-stack dev crafting scalable apps with [NET - Azure], [Angular - React], Git, SQL & extensions. Clean code, dark themes, atomic commits

💬 Have you ever battled tool/runtime version mismatches in EF Core? What did you learn from it?

Top comments (0)