elsa-workflows/elsa-core · error · InvalidOperationException

Adapter settings migrations must define an adapter type and…

Error message

Adapter settings migrations must define an adapter type and a positive source version.

What it means

BuildMigrationIndex validates every registered IAdapterSettingsMigration at service construction: each must declare a non-empty AdapterType and a FromVersion of at least 1. A migration with a blank type or FromVersion <= 0 cannot be indexed and fails fast with this error.

Solutions

1. Set AdapterType and FromVersion in the migration's constructor to valid values (type non-empty, FromVersion >= 1).
2. Fix the configuration/DI wiring that produces empty values.
3. Add unit tests instantiating every migration and asserting valid AdapterType/FromVersion.

Example fix

// before
public MyAdapterMigration() { } // AdapterType null, FromVersion 0
// after
public MyAdapterMigration() { AdapterType = "my-adapter"; FromVersion = 1; ToVersion = 2; }

foreach (var m in migrations)
    if (string.IsNullOrWhiteSpace(m.AdapterType) || m.FromVersion <= 0)
        throw new InvalidOperationException($"Invalid migration registration: type='{m.AdapterType}', from={m.FromVersion}");

try { app = builder.Build(); }
catch (InvalidOperationException ex) when (ex.Message.Contains("must define an adapter type"))
{ /* fail startup with a clear message naming the bad migration */ }

When it happens

Trigger: Registering an IAdapterSettingsMigration whose AdapterType is null/empty/whitespace or whose FromVersion is 0 or negative — typically a default-constructed or misconfigured migration class.

Common situations: New migration implementations forgetting to set AdapterType; version constants defaulting to 0; DI-registered migrations where config that supplies the type/version failed to bind.

Understand the failure class

Background: "missing required argument" and "the following required arguments were not provided": what required-argument errors mean and how to fix them — this error's family across 20 libraries.

Related errors

• The OpenID Connect connection configuration is invalid.
• OpenID Connect settings must be an object.
• The adapter type ' ' is not installed or deployment-allowed.
• Settings version is not compatible with adapter ' ' version…
• Adapter ' ' does not provide a settings migration from…

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

Appendix: source

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

                throw new InvalidOperationException($"Adapter '{adapterType}' has an invalid settings migration from version {version} to {migration.ToVersion}.");
            if (++stepCount > 64)
                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)