stride3d/stride · error · ArgumentException

The upgrader has a target version higher that the current…

Error message

The upgrader has a target version higher that the current version.

What it means

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.

Solutions

1. Lower the upgrader's targetVersion so it does not exceed the collection's currentVersion.
2. If the asset format genuinely supports the newer version, update the collection's currentVersion to at least targetVersion.
3. Verify the correct AssetUpgraderCollection/version constants are being used for this asset type.
4. Register the upgrader only after the package version bump is merged.

Example fix

// before
collection.RegisterUpgrader(typeof(MyUpgrader), new PackageVersion(4, 0, 0, 0), new PackageVersion(4, 2, 0, 0)); // currentVersion = 4.1.0.0
// after
collection.RegisterUpgrader(typeof(MyUpgrader), new PackageVersion(4, 0, 0, 0), new PackageVersion(4, 1, 0, 0));

var target = PackageVersion.Parse(targetVersionStr);
if (target > collection.CurrentVersion)
    throw new InvalidOperationException($"Upgrader target {target} exceeds current asset version {collection.CurrentVersion}");

static bool WithinCurrentVersion(PackageVersion target, PackageVersion current) => target <= current;

try
{
    collection.RegisterUpgrader(upgraderType, start, target);
}
catch (ArgumentException ex)
{
    logger.Error($"Cannot register {upgraderType.Name}: {ex.Message}");
}

When it happens

Trigger: 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.

Common situations: 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.

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

• The target version is lower or equal to the start version.
• The upgrader overlaps with another upgrader.
• No upgrader for asset type
• No upgrader found for version
• Type [ ] must be assignable to Asset

AI-assisted analysis of stride3d/stride@96fad776d2 (2026-09-14). Data as JSON: /api/errors/8cc67ea39aa07b51. Report an issue: GitHub.

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/AssetUpgraderCollection.cs:53

    private readonly SortedList<VersionRange, Type> upgraders = [];
    private readonly Dictionary<Type, IAssetUpgrader> instances = [];
    private readonly PackageVersion currentVersion;

    public AssetUpgraderCollection(Type assetType, PackageVersion currentVersion)
    {
        this.currentVersion = currentVersion;
        AssetRegistry.IsAssetOrPackageType(assetType, true);
        AssetType = assetType;
    }

    public Type AssetType { get; }

    internal void RegisterUpgrader(Type upgraderType, PackageVersion startVersion, PackageVersion targetVersion)
    {
        lock (upgraders)
        {
            if (targetVersion > currentVersion)
                throw new ArgumentException("The upgrader has a target version higher that the current version.");

            var range = new VersionRange(startVersion, targetVersion);

            if (upgraders.Any(x => x.Key.Overlap(range)))
            {
                throw new ArgumentException("The upgrader overlaps with another upgrader.");
            }

            upgraders.Add(new VersionRange(startVersion, targetVersion), upgraderType);
        }
    }

    internal void Validate(PackageVersion minVersion)
    {
        lock (upgraders)
        {
            var version = minVersion;
            foreach (var upgrader in upgraders)

View on GitHub (pinned to 96fad776d2)