{"record":{"id":"8cc67ea39aa07b51","repo":"stride3d/stride","slug":"the-upgrader-has-a-target-version-higher-that-the-current","errorCode":null,"errorMessage":"The upgrader has a target version higher that the current version.","messagePattern":"The upgrader has a target version higher that the current version\\.","errorType":"exception","errorClass":"ArgumentException","httpStatus":null,"severity":"error","filePath":"sources/assets/Stride.Core.Assets/AssetUpgraderCollection.cs","lineNumber":53,"sourceCode":"    private readonly SortedList<VersionRange, Type> upgraders = [];\n    private readonly Dictionary<Type, IAssetUpgrader> instances = [];\n    private readonly PackageVersion currentVersion;\n\n    public AssetUpgraderCollection(Type assetType, PackageVersion currentVersion)\n    {\n        this.currentVersion = currentVersion;\n        AssetRegistry.IsAssetOrPackageType(assetType, true);\n        AssetType = assetType;\n    }\n\n    public Type AssetType { get; }\n\n    internal void RegisterUpgrader(Type upgraderType, PackageVersion startVersion, PackageVersion targetVersion)\n    {\n        lock (upgraders)\n        {\n            if (targetVersion > currentVersion)\n                throw new ArgumentException(\"The upgrader has a target version higher that the current version.\");\n\n            var range = new VersionRange(startVersion, targetVersion);\n\n            if (upgraders.Any(x => x.Key.Overlap(range)))\n            {\n                throw new ArgumentException(\"The upgrader overlaps with another upgrader.\");\n            }\n\n            upgraders.Add(new VersionRange(startVersion, targetVersion), upgraderType);\n        }\n    }\n\n    internal void Validate(PackageVersion minVersion)\n    {\n        lock (upgraders)\n        {\n            var version = minVersion;\n            foreach (var upgrader in upgraders)","sourceCodeStart":35,"sourceCodeEnd":71,"githubUrl":"https://github.com/stride3d/stride/blob/96fad776d210c221682aac1ccdf4c79dc046fc38/sources/assets/Stride.Core.Assets/AssetUpgraderCollection.cs#L35-L71","documentation":"AssetUpgraderCollection.RegisterUpgrader records an upgrader type for a version range [startVersion, targetVersion] under a lock. Before registering, it checks that the range's target does not exceed the collection's currentVersion (the package version the asset format has reached). An upgrader claiming to upgrade to a version beyond the current format is invalid, so it throws ArgumentException.","triggerScenarios":"Calling RegisterUpgrader (directly or via AssetUpgraderAttribute discovery during package/assembly registration) with a targetVersion PackageVersion greater than the currentVersion passed to the AssetUpgraderCollection constructor — e.g. registering an upgrader targeting 4.2.0.0 in a collection built for current version 4.1.0.0.","commonSituations":"Defining an upgrader for a future asset version before bumping the asset type's current package version; reusing an upgrader from a newer branch in an older codebase; typos in version constants where target exceeds the declared current asset version.","solutions":["Lower the upgrader's targetVersion so it does not exceed the collection's currentVersion.","If the asset format genuinely supports the newer version, update the collection's currentVersion to at least targetVersion.","Verify the correct AssetUpgraderCollection/version constants are being used for this asset type.","Register the upgrader only after the package version bump is merged."],"exampleFix":"// before\ncollection.RegisterUpgrader(typeof(MyUpgrader), new PackageVersion(4, 0, 0, 0), new PackageVersion(4, 2, 0, 0)); // currentVersion = 4.1.0.0\n// after\ncollection.RegisterUpgrader(typeof(MyUpgrader), new PackageVersion(4, 0, 0, 0), new PackageVersion(4, 1, 0, 0));","handlingStrategy":"validation","validationCode":"var target = PackageVersion.Parse(targetVersionStr);\nif (target > collection.CurrentVersion)\n    throw new InvalidOperationException($\"Upgrader target {target} exceeds current asset version {collection.CurrentVersion}\");","typeGuard":"static bool WithinCurrentVersion(PackageVersion target, PackageVersion current) => target <= current;","tryCatchPattern":"try\n{\n    collection.RegisterUpgrader(upgraderType, start, target);\n}\ncatch (ArgumentException ex)\n{\n    logger.Error($\"Cannot register {upgraderType.Name}: {ex.Message}\");\n}","preventionTips":["Bump the asset type's current package version before or together with adding a new upgrader.","Derive upgrader target versions from the same constants used for the current version.","Add a startup test validating all registered upgrader targets against currentVersion."],"tags":["versioning","asset-upgrade","argument-validation","registration"],"backgroundTag":"value-out-of-range","analyzedSha":"96fad776d210c221682aac1ccdf4c79dc046fc38","analyzedAt":"2026-09-14T02:59:31.279Z","contentChangedAt":"2026-09-14T02:59:31.279Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}