AvaloniaUI/Avalonia · error · ArgumentException

Folder path is expected to be an absolute link with "file" o

Error message

Folder path is expected to be an absolute link with "file" or "content" scheme.

What it means

Thrown by AndroidStorageProvider.TryGetFolderFromPathAsync when the supplied Uri is not absolute or its Scheme is neither "file" nor "content". Same scheme requirement as the file variant: Android folders must be addressed via file:// or content://.

Source

Thrown at src/Android/Avalonia.Android/Platform/Storage/AndroidStorageProvider.cs:83

        var javaFile = new JavaFile(androidUriPath);
        if (javaFile.Exists() && javaFile.IsFile)
        {
            return new BclStorageFile(new System.IO.FileInfo(javaFile.AbsolutePath));
        }

        return null;
    }

    public async Task<IStorageFolder?> TryGetFolderFromPathAsync(Uri folderPath)
    {
        if (folderPath is null)
        {
            throw new ArgumentNullException(nameof(folderPath));
        }

        if (folderPath is not { IsAbsoluteUri: true, Scheme: "file" or "content" })
        {
            throw new ArgumentException("Folder path is expected to be an absolute link with \"file\" or \"content\" scheme.");
        }

        var androidUri = AndroidUri.Parse(folderPath.ToString());
        if (androidUri?.Path is not {} androidUriPath)
        {
            return null;
        }

        var javaFile = new JavaFile(androidUriPath);
        if (javaFile.Exists() && javaFile.IsDirectory)
        {
            return new BclStorageFolder(new System.IO.DirectoryInfo(javaFile.AbsolutePath));
        }

        return null;
    }

    public Task<IStorageFolder?> TryGetWellKnownFolderAsync(WellKnownFolder wellKnownFolder)

View on GitHub (pinned to 11c5427268)

Solutions

1. Build an absolute file:// or content:// URI before calling: new Uri(folderPath, UriKind.Absolute).
2. For filesystem paths, wrap as file:// via Path.GetFullPath + Uri construction.
3. Validate Uri.IsAbsoluteUri && Uri.Scheme in {"file","content"} upstream and convert or reject.
4. Forward content:// folder URIs (e.g. from tree pickers) verbatim.

Example fix

// before
var folder = await provider.TryGetFolderFromPathAsync(new Uri("/sdcard/Pictures"));

// after
var abs = System.IO.Path.GetFullPath("/sdcard/Pictures");
var folder = await provider.TryGetFolderFromPathAsync(new Uri($"file://{abs}"));

// validate scheme before calling the provider
if (folderPath is not { IsAbsoluteUri: true } || (folderPath.Scheme != "file" && folderPath.Scheme != "content"))
    throw new ArgumentException("Use an absolute file:// or content:// URI.");
var folder = await provider.TryGetFolderFromPathAsync(folderPath);

static bool IsValidAndroidStorageUri(Uri? u) => u is { IsAbsoluteUri: true } && (u.Scheme == "file" || u.Scheme == "content");

When it happens

Trigger: Calling TryGetFolderFromPathAsync with a relative Uri or an absolute Uri whose scheme is not file/content (e.g. http, custom scheme, or a malformed path).

Common situations: Passing a directory path string instead of a properly-formed file:// URI; cross-platform code sharing a Uri of a different scheme; UriKind defaulting to relative for certain escaped inputs; receiving folder paths from desktop/iOS into Android.

Related errors

• File path is expected to be an absolute link with "file" or
• StorageItem is not a file
• StorageItem is not a writeable file
• Unable to create item in the requested directory
• Unable to move item to the requested directory

AI-assisted analysis of AvaloniaUI/Avalonia@11c5427268 (2026-08-13). Data as JSON: /api/errors/cc83f8006b3a30d5. Report an issue: GitHub.