stride3d/stride · error · ArgumentException

Base path must be absolute, got

Error message

Base path must be absolute, got '{basePath}'.

What it means

FileSystemProvider's ChangeBasePath validates a new base path. Passing a relative path (or empty string) is rejected because all file URLs would be resolved against it; only an absolute path — or null for pure passthrough mode — is allowed.

Solutions

1. Prefix the path with the application's root directory (Path.GetFullPath or combining with AppContext.BaseDirectory / a known mount point)
2. Pass null instead of "" when passthrough (no base path rewriting) is intended
3. Trim/validate the configured value before calling ChangeBasePath

Example fix

// before
provider.ChangeBasePath(config.BasePath); // "data"
// after
var full = Path.IsPathRooted(config.BasePath) ? config.BasePath : Path.Combine(AppContext.BaseDirectory, config.BasePath);
provider.ChangeBasePath(full);

if (string.IsNullOrWhiteSpace(basePath)) throw new ArgumentException("Base path must be non-empty; use null for passthrough.");
if (!Path.IsPathRooted(basePath)) basePath = Path.GetFullPath(Path.Combine(AppContext.BaseDirectory, basePath));

static bool IsUsableBasePath(string p) => p is null || (p.Length > 0 && Path.IsPathRooted(p));

When it happens

Trigger: Calling ChangeBasePath with a value like "data" or "./data" that fails Path.IsPathRooted, or with an empty/whitespace string.

Common situations: Building a base path by string concatenation without a root (e.g. joining a config folder name to a filename), reading basePath from config where an env var is unset, or passing "" intending 'no base path' instead of null.

Understand the failure class

Background: "Invalid value" and "allowed values are" config errors: what your library rejected and how to fix it — this error's family across 41 libraries.

Related errors

• The relativePath argument is null or empty
• Base path must be non-empty (use null for passthrough).
• Trying to convert back a path that is not in this file…
• Count cannot be less than zero
• The target version is lower or equal to the start version.

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

Appendix: source

Thrown at sources/core/Stride.Core.IO/FileSystemProvider.cs:39

    /// Initializes a new instance of the <see cref="FileSystemProvider" /> class with the given base path.
    /// </summary>
    /// <param name="rootPath">The root path of this provider.</param>
    /// <param name="localBasePath">The path to a local directory where this instance will load the files from.</param>
    public FileSystemProvider(string rootPath, string? localBasePath) : base(rootPath)
    {
        ChangeBasePath(localBasePath);
    }

    public void ChangeBasePath(string? basePath)
    {
        // Empty resolves to OS filesystem root, relative resolves to CWD — both surprising.
        // null stays allowed (constructor passthrough mode).
        if (basePath is not null)
        {
            if (string.IsNullOrWhiteSpace(basePath))
                throw new ArgumentException("Base path must be non-empty (use null for passthrough).", nameof(basePath));
            if (!Path.IsPathRooted(basePath))
                throw new ArgumentException($"Base path must be absolute, got '{basePath}'.", nameof(basePath));
        }

        localBasePath = basePath?.Replace(AltDirectorySeparatorChar, DirectorySeparatorChar);

        // Ensure localBasePath ends with a \
        if (localBasePath?.EndsWith(DirectorySeparatorChar) == false)
            localBasePath += DirectorySeparatorChar;
    }

    protected virtual string ConvertUrlToFullPath(string url)
    {
        if (localBasePath == null)
            return url;
        return localBasePath + url.Replace(VirtualFileSystem.DirectorySeparatorChar, DirectorySeparatorChar);
    }

    protected virtual string ConvertFullPathToUrl(string path)
    {

View on GitHub (pinned to 96fad776d2)