stride3d/stride · error · ArgumentException

Base path must be non-empty (use null for passthrough).

Error message

Base path must be non-empty (use null for passthrough).

What it means

FileSystemProvider.ChangeBasePath validates the new base path: null is allowed (passthrough to OS filesystem), but an empty/whitespace path or a relative path throws ArgumentException, because those silently resolve to the OS root or CWD, which is considered surprising and error-prone.

Solutions

1. Pass an absolute path (Path.GetFullPath / Path.Combine(AppContext.BaseDirectory, rel)) before calling
2. Pass null explicitly when passthrough to the OS filesystem is intended
3. Validate config values: treat empty base path config as 'use default' mapping to null, not ""
4. Catch ArgumentException and log the offending value for config diagnosis

Example fix

// before
provider.ChangeBasePath(config.BasePath); // may be "" or "data"
// after
provider.ChangeBasePath(string.IsNullOrWhiteSpace(config.BasePath)
    ? null
    : Path.GetFullPath(config.BasePath));

bool valid = basePath is null ||
    (!string.IsNullOrWhiteSpace(basePath) && Path.IsPathRooted(basePath));

try { provider.ChangeBasePath(p); }
catch (ArgumentException ex) { /* log config error, fall back to null passthrough */ }

When it happens

Trigger: Calling ChangeBasePath(""), ChangeBasePath(" "), or ChangeBasePath("relative/dir") on a FileSystemProvider; constructing a provider then re-basing it with a config value that is empty or relative.

Common situations: Config files with unset/blank base path fields; deriving base path from environment variables that are empty; passing user-supplied relative paths (e.g. './data') without resolving them first.

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

• Base path must be absolute, got
• Trying to convert back a path that is not in this file…
• ' ' has no parent app directory.
• ' ' has no store base directory.
• The provided path is not a valid path name.

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

Appendix: source

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

    /// <summary>
    /// 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);
    }

View on GitHub (pinned to 96fad776d2)