stride3d/stride · error · ArgumentException

The assetUpgraderType must implement IAssetUpgrader…

Error message

The assetUpgraderType must implement IAssetUpgrader interface

What it means

The AssetUpgraderAttribute constructor validates that the supplied assetUpgraderType implements IAssetUpgrader and throws ArgumentException otherwise. The attribute's whole purpose is to point migration machinery at an executable upgrader, so a non-implementing type is a construction-time configuration error.

Solutions

Make the referenced type implement Stride.Core.Assets.IAssetUpgrader (or derive from AssetUpgraderBase).
Fix the typeof(...) argument to point at the actual upgrader class.
Move to the generic AssetUpgraderAttribute<T> form so the compiler enforces the constraint.

Example fix

// before
[AssetUpgrader("Game", "Level", "1.0.0", "1.1.0", typeof(LevelPatcher))]
public class LevelPatcher { }
// after
public class LevelPatcher : AssetUpgraderBase { ... }

Defensive patterns

Strategy: type-guard

Validate before calling

if (!typeof(IAssetUpgrader).IsAssignableFrom(upgraderType)) throw new ArgumentException($"{upgraderType} must implement IAssetUpgrader");

Type guard

bool IsUpgraderType(Type t) => typeof(IAssetUpgrader).IsAssignableFrom(t);

Try / catch

try { var attr = new AssetUpgraderAttribute(name, start, target, upgraderType); } catch (ArgumentException ex) when (ex.Message.Contains("IAssetUpgrader")) { log.Error($"Bad upgrader type: {upgraderType}"); }

Prevention

Prefer the generic AssetUpgraderAttribute<T> so the compiler enforces the interface.
Keep all upgraders derived from AssetUpgraderBase.
Recheck typeof(...) arguments after interface renames/refactors.

When it happens

Trigger: Applying [AssetUpgrader(name, start, target, typeof(SomeClass))] where SomeClass does not implement IAssetUpgrader (or implements the wrong interface).

Common situations: Typo/wrong type passed to the attribute; refactoring renamed the interface; author implemented IAssetComparable or a custom method but not IAssetUpgrader.

Understand the failure class

Background: "Must be a positive integer", "Invalid value", "Unsupported": the invalid-argument-value error family, when a library rejects the value you pass — this error's family across 35 libraries.

Related errors

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

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/AssetUpgraderAttribute.cs:25

/// </summary>
[AttributeUsage(AttributeTargets.Class, AllowMultiple = true)]
public class AssetUpgraderAttribute : Attribute
{
    /// <summary>
    /// Initializes a new instance of the <see cref="AssetUpgraderAttribute"/> with a range of supported initial version numbers.
    /// </summary>
    /// <param name="name">The dependency name.</param>
    /// <param name="startMinVersion">The minimal initial version number this upgrader can work on.</param>
    /// <param name="targetVersion">The target version number of this upgrader.</param>
    /// <param name="assetUpgraderType">The type of upgrader to instantiate to upgrade the asset.</param>
    public AssetUpgraderAttribute(string name, string startMinVersion, string targetVersion, Type assetUpgraderType)
    {
        Name = name;
        StartVersion = PackageVersion.Parse(startMinVersion);
        TargetVersion = PackageVersion.Parse(targetVersion);

        if (!typeof(IAssetUpgrader).IsAssignableFrom(assetUpgraderType))
            throw new ArgumentException("The assetUpgraderType must implement IAssetUpgrader interface", nameof(assetUpgraderType));
        if (TargetVersion <= StartVersion)
            throw new ArgumentException("The target version is lower or equal to the start version.", nameof(targetVersion));
        AssetUpgraderType = assetUpgraderType;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="AssetUpgraderAttribute"/> with a single supported initial version number.
    /// </summary>
    /// <param name="name">The dependency name.</param>
    /// <param name="startVersion">The initial version number this upgrader can work on.</param>
    /// <param name="targetVersion">The target version number of this upgrader.</param>
    /// <param name="assetUpgraderType">The type of upgrader to instantiate to upgrade the asset.</param>
    public AssetUpgraderAttribute(string name, int startVersion, int targetVersion, Type assetUpgraderType)
        : this(name, "0.0." + startVersion, "0.0." + targetVersion, assetUpgraderType)
    {
    }

    /// <summary>

View on GitHub (pinned to 96fad776d2)