elsa-workflows/elsa-core · error · InvalidOperationException

Settings version is not compatible with adapter ' ' version…

Error message

Settings version {settingsVersion} is not compatible with adapter '{adapterType}' version {currentVersion}.

What it means

MigrateAsync rejects a settings version that is non-positive or greater than the adapter's current described SettingsVersion. Version 0 or negative means corrupt input; a version above the adapter's current version means the settings were written by a newer adapter than the one deployed.

Solutions

Upgrade the adapter to a version whose SettingsVersion is >= the stored settings version.
Reset the stored settings to a supported version or re-create the connection settings.
Guard the call: compare stored version to adapter.Describe().SettingsVersion before invoking migration.

Example fix

// before
await service.MigrateAsync(adapterType, storedVersion, settings);
// after
var current = adapters.Get(adapterType).Describe().SettingsVersion;
if (storedVersion < 1 || storedVersion > current)
    throw new InvalidOperationException($"Stored settings version {storedVersion} unsupported for adapter version {current}.");
await service.MigrateAsync(adapterType, storedVersion, settings);

Defensive patterns

Strategy: validation

Validate before calling

var current = adapters.Get(adapterType).Describe().SettingsVersion;
if (storedVersion is < 1 || storedVersion > current)
    throw new InvalidOperationException($"Version {storedVersion} outside supported range 1..{current}");

Try / catch

try { await service.MigrateAsync(type, storedVersion, settings); }
catch (InvalidOperationException ex) when (ex.Message.Contains("is not compatible"))
{ /* flag downgrade; require adapter upgrade or settings reset */ }

Prevention

Never roll back adapter versions without a data plan
Store settings version alongside settings and validate on startup
Alert on settings versions newer than the deployed adapter

When it happens

Trigger: Migrating stored settings whose SettingsVersion is <= 0, or whose version exceeds adapter.Describe().SettingsVersion — e.g. downgrading the adapter package while old settings remain.

Common situations: Rolling back the adapter NuGet/app version after settings were migrated forward; hand-edited settings JSON with a bad version; corrupted rows.

Understand the failure class

Background: "value must be between 0 and 1" / "out of range" / "must not be negative" errors: fixing range-validation failures across open-source libraries — this error's family across 42 libraries.

Related errors

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

Appendix: source

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

    IExternalAuthenticationAdapterRegistry adapters,
    IEnumerable<IAdapterSettingsMigration> migrations) : IAdapterSettingsMigrationService
{
    private readonly IReadOnlyDictionary<(string AdapterType, int FromVersion), IAdapterSettingsMigration> _migrations =
        BuildMigrationIndex(migrations);

    public async ValueTask<AdapterSettingsMigrationResult> MigrateAsync(
        string adapterType,
        int settingsVersion,
        JsonElement settings,
        CancellationToken cancellationToken = default)
    {
        cancellationToken.ThrowIfCancellationRequested();
        if (!adapters.TryGet(adapterType, out var adapter))
            throw new InvalidOperationException($"The adapter type '{adapterType}' is not installed or deployment-allowed.");

        var currentVersion = adapter.Describe().SettingsVersion;
        if (settingsVersion <= 0 || settingsVersion > currentVersion)
            throw new InvalidOperationException($"Settings version {settingsVersion} is not compatible with adapter '{adapterType}' version {currentVersion}.");
        if (settingsVersion == currentVersion)
            return new(currentVersion, settings.Clone(), false);

        var migrated = settings.Clone();
        var version = settingsVersion;
        var stepCount = 0;
        while (version < currentVersion)
        {
            if (!_migrations.TryGetValue((adapterType, version), out var migration))
                throw new InvalidOperationException($"Adapter '{adapterType}' does not provide a settings migration from version {version}.");
            if (migration.ToVersion <= version || migration.ToVersion > currentVersion)
                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;
        }

View on GitHub (pinned to fe9217bdfa)