elsa-workflows/elsa-core · error · InvalidOperationException

Adapter ' ' registers more than one migration from version .

Error message

Adapter '{migration.AdapterType}' registers more than one migration from version {migration.FromVersion}.

What it means

BuildMigrationIndex keys migrations by (AdapterType, FromVersion); two migrations claiming the same adapter type and source version are ambiguous, so registration fails fast with this error instead of picking one nondeterministically.

Solutions

Remove or consolidate the duplicate migration so only one exists per (AdapterType, FromVersion).
Bump FromVersion/ToVersion on the new migration so it chains rather than collides.
Audit DI registrations to ensure each migration type is added once.

Example fix

// before
services.AddSingleton<IAdapterSettingsMigration>(new MyMigration(1, 2));
services.AddSingleton<IAdapterSettingsMigration>(new MyMigrationV2(1, 2)); // duplicate
// after
services.AddSingleton<IAdapterSettingsMigration>(new MyMigrationV2(1, 2));

Defensive patterns

Strategy: try-catch

Validate before calling

var seen = new HashSet<(string,int)>();
foreach (var m in migrations)
    if (!seen.Add((m.AdapterType, m.FromVersion)))
        throw new InvalidOperationException($"Duplicate migration for {m.AdapterType} from {m.FromVersion}");

Try / catch

try { app = builder.Build(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("more than one migration"))
{ /* identify and remove the duplicate registration at startup */ }

Prevention

Delete superseded migration classes when adding replacements
Register each migration exactly once in DI
Branch-merge checklist: search for migrations added from the same version

When it happens

Trigger: Registering two IAdapterSettingsMigration implementations with identical AdapterType and FromVersion — e.g. an old migration class left in place while a replacement with the same FromVersion was added.

Common situations: Copy-pasting a migration class without changing FromVersion; accidentally registering the same migration type twice in DI; merging branches that each added a migration from the same version.

Understand the failure class

Background: Conflicting config options: "cannot be used together" — configuration validation errors across open-source libraries — this error's family across 162 libraries.

Related errors

AI-assisted analysis of elsa-workflows/elsa-core@fe9217bdfa (2026-09-13). Data as JSON: /api/errors/c83e2f6d387c1a86. Report an issue: GitHub.

Appendix: source

Thrown at src/modules/Elsa.ExternalAuthentication/Services/AdapterSettingsMigrationService.cs:62

                throw new InvalidOperationException($"Adapter '{adapterType}' settings migration contains a cycle.");

            migrated = (await migration.MigrateAsync(migrated, cancellationToken)).Clone();
            version = migration.ToVersion;
        }

        return new(version, migrated, true);
    }

    private static IReadOnlyDictionary<(string AdapterType, int FromVersion), IAdapterSettingsMigration> BuildMigrationIndex(
        IEnumerable<IAdapterSettingsMigration> migrations)
    {
        var result = new Dictionary<(string AdapterType, int FromVersion), IAdapterSettingsMigration>();
        foreach (var migration in migrations)
        {
            if (string.IsNullOrWhiteSpace(migration.AdapterType) || migration.FromVersion <= 0)
                throw new InvalidOperationException("Adapter settings migrations must define an adapter type and a positive source version.");
            if (!result.TryAdd((migration.AdapterType, migration.FromVersion), migration))
                throw new InvalidOperationException($"Adapter '{migration.AdapterType}' registers more than one migration from version {migration.FromVersion}.");
        }
        return result;
    }
}

View on GitHub (pinned to fe9217bdfa)