dotnet/maui · error · ArgumentException

Invalid Uri

Error message

Invalid Uri

What it means

Platform.cs throws ArgumentException("Invalid Uri", "Source") when a file-style Uri (file:// or app local) does not start with /local or /temp. The platform only resolves two well-known iOS app sandbox prefixes for local file paths; anything else is rejected as invalid source.

Source

Thrown at src/Compatibility/Core/src/iOS/Platform.cs:656

		internal static string ResolveMsAppDataUri(Uri uri)
		{
			if (uri.Scheme == "ms-appdata")
			{
				string filePath = string.Empty;

				if (uri.LocalPath.StartsWith("/local"))
				{
					var libraryPath = NSFileManager.DefaultManager.GetUrls(NSSearchPathDirectory.LibraryDirectory, NSSearchPathDomain.User)[0].Path;
					filePath = IOPath.Combine(libraryPath, uri.LocalPath.Substring(7));
				}
				else if (uri.LocalPath.StartsWith("/temp"))
				{
					filePath = IOPath.Combine(IOPath.GetTempPath(), uri.LocalPath.Substring(6));
				}
				else
				{
					throw new ArgumentException("Invalid Uri", "Source");
				}

				return filePath;
			}
			else
			{
				throw new ArgumentException("uri");
			}
		}

		internal void SubscribeToAlertsAndActionSheets()
		{
			var busyCount = 0;
			MessagingCenter.Subscribe(this, Page.BusySetSignalName, (Page sender, bool enabled) =>
			{
				if (!PageIsChildOfPlatform(sender))
					return;
				busyCount = Math.Max(0, enabled ? busyCount + 1 : busyCount - 1);

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Use /local (Library) or /temp (Tmp) prefixed paths for file Uris on iOS.
2. Prefer FileImageSource or bundle resources rather than raw file Uris.
3. If you must reference Documents, copy the file into Library or Tmp first.

Example fix

// before
new UriImageSource { Uri = new Uri("file:///documents/img.png") };
// after
// copy file into LibraryDirectory, then:
new UriImageSource { Uri = new Uri("file:///local/img.png") };

// Validate the local-path prefix before resolving.
if (!uri.LocalPath.StartsWith("/local") && !uri.LocalPath.StartsWith("/temp"))
    throw new ArgumentException("Uri must reference /local (Library) or /temp on iOS.");

static bool IsRecognizedLocalUri(Uri u) =>
    u != null && u.IsAbsoluteUri &&
    (u.LocalPath.StartsWith("/local") || u.LocalPath.StartsWith("/temp"));

When it happens

Trigger: Passing a Uri to the platform whose LocalPath does not begin with /local or /temp; e.g. an absolute filesystem path encoded as a Uri with a different prefix, or a malformed app-resource Uri.

Common situations: Loading images/files via UriSource with paths outside the recognized sandbox; copying files to Documents but referencing with /documents prefix; bundling resource Uris that don't match the local/temp convention; cross-platform code passing platform-specific paths.

Related errors

• uri
• indexPath
• group
• indexPath
• view

AI-assisted analysis of dotnet/maui@f377ff1c5e (2026-08-13). Data as JSON: /api/errors/15e61e2698f5d327. Report an issue: GitHub.