stride3d/stride · error · ArgumentException

filePath must be relative

Error message

filePath must be relative

What it means

PackageLoadingAssetFile's constructor requires a relative asset file path (relative to the package's default asset folder). The library throws ArgumentException when a UFile with an absolute path is passed, because it later combines it with SourceFolder and an absolute path would produce an invalid combined path.

Solutions

1. Convert the absolute path to a package-relative one before constructing (make it relative to the default asset folder / SourceFolder)
2. Use the UFile/UDirectory helpers to strip the folder prefix
3. Ensure the caller stores relative paths in config/serialization

Example fix

// before
var file = new UFile(@"C:\MyGame\Assets\box.sdtex");
var item = new PackageLoadingAssetFile(package, file, null);
// after
var file = new UFile(@"C:\MyGame\Assets\box.sdtex");
var rel = new UFile(file.MakeRelative(new UDirectory(package.RootDirectory + "/Assets")));
var item = new PackageLoadingAssetFile(package, rel, null);

if (filePath == null || filePath.IsAbsolute)
    throw new ArgumentException("Pass a path relative to the package's default asset folder", nameof(filePath));

bool IsRelativePath(UFile f) => f != null && !f.IsAbsolute;

When it happens

Trigger: Calling new PackageLoadingAssetFile(package, filePath, sourceFolder) with a UFile whose IsAbsolute is true, e.g. 'C:/proj/assets/myasset.sdtex' instead of 'myasset.sdtex'.

Common situations: Paths built from File.OpenDialog results, Environment.CurrentDirectory concatenation, or full paths loaded from config/serialized data instead of package-relative paths.

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

• A part Id cannot be empty.
• Expecting relative path
• Cannot add an empty asset item reference
• Cannot find the specified AssetItem instance in the session
• Invalid relative path. Expecting an absolute project path

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

Appendix: source

Thrown at sources/assets/Stride.Core.Assets/PackageLoadingAssetFile.cs:54

    /// <param name="sourceFolder">The source folder.</param>
    public PackageLoadingAssetFile(UFile filePath, UDirectory sourceFolder)
    {
        FilePath = filePath;
        OriginalFilePath = FilePath;
        SourceFolder = sourceFolder;
    }

    /// <summary>
    /// Initializes a new instance of the <see cref="PackageLoadingAssetFile" /> class.
    /// </summary>
    /// <param name="package">The package this asset will be part of.</param>
    /// <param name="filePath">The relative file path (from default asset folder).</param>
    /// <param name="sourceFolder">The source folder (optional, can be null).</param>
    /// <exception cref="ArgumentException">filePath must be relative</exception>
    public PackageLoadingAssetFile(Package package, UFile filePath, UDirectory sourceFolder)
    {
        if (filePath.IsAbsolute)
            throw new ArgumentException("filePath must be relative", filePath);

        SourceFolder = UPath.Combine(package.RootDirectory!, sourceFolder ?? package.GetDefaultAssetFolder());
        FilePath = UPath.Combine(SourceFolder, filePath);
        OriginalFilePath = FilePath;
    }

    public IReference ToReference()
    {
        return new AssetReference(AssetId.Empty, AssetLocation);
    }

    public YamlAsset? AsYamlAsset()
    {
        // The asset file might have been been marked as deleted during the run of asset upgrader. In this case let's just return null.
        if (Deleted)
            return null;

        try

View on GitHub (pinned to 96fad776d2)