abpframework/abp · error · Exception

Migrations failed! A migration command didn't run successful

Error message

Migrations failed! A migration command didn't run successfully.

What it means

Thrown by CreateMigrationAndRunMigratorCommand when _initialMigrationCreator.CreateAsync returns false, indicating that the EF Core migration command ('dotnet ef migrations add ...') failed to execute successfully. This is a downstream failure: the migration creation step itself errored, so this exception propagates the failure to the caller. The error is logged via Logger.LogError before throwing.

Source

Thrown at framework/src/Volo.Abp.Cli.Core/Volo/Abp/Cli/Commands/CreateMigrationAndRunMigratorCommand.cs:70

        if (migrationsCreatedSuccessfully)
        {
            if (nolayers)
            {
                CmdHelper.RunCmd("dotnet run --migrate-database", Path.GetDirectoryName(Path.Combine(dbMigrationsFolder, "MyCompanyName.MyProjectName")));
            }
            else
            {
                CmdHelper.RunCmd("dotnet run",  Path.GetDirectoryName(dbMigratorProjectPath));
            }
            await Task.CompletedTask;
        }
        else
        {
            var exceptionMsg = "Migrations failed! A migration command didn't run successfully.";

            Logger.LogError(exceptionMsg);
            throw new Exception(exceptionMsg);
        }
    }
    
    private static string GetDbMigratorProjectPath(string dbMigrationsFolderPath)
    {
        var srcFolder = Directory.GetParent(dbMigrationsFolderPath);
        var dbMigratorDirectory = Directory.GetDirectories(srcFolder.FullName)
            .FirstOrDefault(d => d.EndsWith(".DbMigrator"));

        return dbMigratorDirectory == null
            ? null
            : Directory.GetFiles(dbMigratorDirectory).FirstOrDefault(f => f.EndsWith(".csproj"));
    }

    public string GetUsageInfo()
    {
        return string.Empty;
    }

View on GitHub (pinned to 7ed43b1931)

Solutions

Install/update EF Core tools: `dotnet tool install --global dotnet-ef` or `dotnet tool update --global dotnet-ef`
Ensure the DbMigrations project builds cleanly: `dotnet build` in the project folder and fix any compilation errors
Check the DbContext and its configuration (connection string, provider package, OnModelCreating) for errors
Verify the EF Core tools version matches the EF Core runtime package version in your .csproj
Run `dotnet ef migrations add InitialCreate` manually in the DbMigrations project to see the detailed error output

Example fix

N/A

Defensive patterns

Strategy: try-catch

Validate before calling

// Pre-flight: ensure EF Core tools are installed and project builds
var efCheck = CmdHelper.RunCmdAndGetOutput("dotnet ef --version");
if (efCheck.ExitCode != 0)
{
    Console.Error.WriteLine("Install dotnet-ef: dotnet tool install --global dotnet-ef");
    return;
}

Try / catch

try
{
    await command.ExecuteAsync(args);
}
catch (Exception ex) when (ex.Message.Contains("Migrations failed"))
{
    logger.LogError("EF Core migration creation failed. Run 'dotnet ef migrations add InitialCreate' manually for details.");
    // The underlying EF error is swallowed; surface it by running the migration manually
}

Prevention

Ensure dotnet-ef global tool is installed and matches the EF Core package version
Build the DbMigrations project successfully before running the migration command
Validate DbContext configuration and connection strings beforehand
Run the EF migration command manually first to catch detailed errors

When it happens

Trigger: InitialMigrationCreator.CreateAsync returns false because the underlying 'dotnet ef migrations add InitialCreate' command failed — causes include missing EF Core tools, invalid DbContext configuration, database connection issues during model snapshot generation, or compilation errors in the migration project.

Common situations: EF Core design-time tools not installed or wrong version, DbContext has configuration errors (missing connection string, invalid provider), the project doesn't compile, or there's a mismatch between EF Core runtime and tools packages. CI environments where dotnet-ef global tool is not pre-installed.

Related errors

AI-assisted analysis of abpframework/abp@7ed43b1931 (2026-08-13). Data as JSON: /api/errors/eef553f23c2b6aeb. Report an issue: GitHub.