{"record":{"id":"1ee7d9ae25562f55","repo":"elsa-workflows/elsa-core","slug":"settings-version-settingsversion-is-not-compatible-with","errorCode":null,"errorMessage":"Settings version {settingsVersion} is not compatible with adapter '{adapterType}' version {currentVersion}.","messagePattern":"Settings version (.+?) is not compatible with adapter '(.+?)' version (.+?)\\.","errorType":"exception","errorClass":"InvalidOperationException","httpStatus":null,"severity":"error","filePath":"src/modules/Elsa.ExternalAuthentication/Services/AdapterSettingsMigrationService.cs","lineNumber":30,"sourceCode":"    IExternalAuthenticationAdapterRegistry adapters,\n    IEnumerable<IAdapterSettingsMigration> migrations) : IAdapterSettingsMigrationService\n{\n    private readonly IReadOnlyDictionary<(string AdapterType, int FromVersion), IAdapterSettingsMigration> _migrations =\n        BuildMigrationIndex(migrations);\n\n    public async ValueTask<AdapterSettingsMigrationResult> MigrateAsync(\n        string adapterType,\n        int settingsVersion,\n        JsonElement settings,\n        CancellationToken cancellationToken = default)\n    {\n        cancellationToken.ThrowIfCancellationRequested();\n        if (!adapters.TryGet(adapterType, out var adapter))\n            throw new InvalidOperationException($\"The adapter type '{adapterType}' is not installed or deployment-allowed.\");\n\n        var currentVersion = adapter.Describe().SettingsVersion;\n        if (settingsVersion <= 0 || settingsVersion > currentVersion)\n            throw new InvalidOperationException($\"Settings version {settingsVersion} is not compatible with adapter '{adapterType}' version {currentVersion}.\");\n        if (settingsVersion == currentVersion)\n            return new(currentVersion, settings.Clone(), false);\n\n        var migrated = settings.Clone();\n        var version = settingsVersion;\n        var stepCount = 0;\n        while (version < currentVersion)\n        {\n            if (!_migrations.TryGetValue((adapterType, version), out var migration))\n                throw new InvalidOperationException($\"Adapter '{adapterType}' does not provide a settings migration from version {version}.\");\n            if (migration.ToVersion <= version || migration.ToVersion > currentVersion)\n                throw new InvalidOperationException($\"Adapter '{adapterType}' has an invalid settings migration from version {version} to {migration.ToVersion}.\");\n            if (++stepCount > 64)\n                throw new InvalidOperationException($\"Adapter '{adapterType}' settings migration contains a cycle.\");\n\n            migrated = (await migration.MigrateAsync(migrated, cancellationToken)).Clone();\n            version = migration.ToVersion;\n        }","sourceCodeStart":12,"sourceCodeEnd":48,"githubUrl":"https://github.com/elsa-workflows/elsa-core/blob/fe9217bdfa0e27f0e09e45006eb6898f616e513d/src/modules/Elsa.ExternalAuthentication/Services/AdapterSettingsMigrationService.cs#L12-L48","documentation":"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.","triggerScenarios":"Migrating stored settings whose SettingsVersion is <= 0, or whose version exceeds adapter.Describe().SettingsVersion — e.g. downgrading the adapter package while old settings remain.","commonSituations":"Rolling back the adapter NuGet/app version after settings were migrated forward; hand-edited settings JSON with a bad version; corrupted rows.","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."],"exampleFix":"// before\nawait service.MigrateAsync(adapterType, storedVersion, settings);\n// after\nvar current = adapters.Get(adapterType).Describe().SettingsVersion;\nif (storedVersion < 1 || storedVersion > current)\n    throw new InvalidOperationException($\"Stored settings version {storedVersion} unsupported for adapter version {current}.\");\nawait service.MigrateAsync(adapterType, storedVersion, settings);","handlingStrategy":"validation","validationCode":"var current = adapters.Get(adapterType).Describe().SettingsVersion;\nif (storedVersion is < 1 || storedVersion > current)\n    throw new InvalidOperationException($\"Version {storedVersion} outside supported range 1..{current}\");","typeGuard":null,"tryCatchPattern":"try { await service.MigrateAsync(type, storedVersion, settings); }\ncatch (InvalidOperationException ex) when (ex.Message.Contains(\"is not compatible\"))\n{ /* flag downgrade; require adapter upgrade or settings reset */ }","preventionTips":["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"],"tags":["configuration","migration","versioning"],"backgroundTag":"value-out-of-range","analyzedSha":"fe9217bdfa0e27f0e09e45006eb6898f616e513d","analyzedAt":"2026-09-13T20:32:34.702Z","contentChangedAt":"2026-09-13T20:32:34.702Z","schemaVersion":2},"datasetVersion":"2026-09-16T04:17:20.429Z"}