What causes "AppLinkUri" in dotnet/maui?

Set AppLinkEntry.AppLinkUri before calling DeregisterLink: `entry.AppLinkUri = new Uri("myapp://detail/42");`

dotnet/maui · error · ArgumentNullException

AppLinkUri

Error message

AppLinkUri

What it means

IOSAppLinks integrates .NET MAUI AppIndexing/AppLinks with iOS CoreSpotlight. DeregisterLink(IAppLinkEntry) removes a previously indexed deep link from Spotlight. It requires appLink.AppLinkUri to be a non-empty URI because that value is the lookup key used to delete the indexed item. Throwing ArgumentNullException here prevents a silent no-op deregistration of an unidentifiable link.

Source

Thrown at src/Compatibility/Core/src/iOS/iOSAppLinks.cs:15

using System;
using System.Threading.Tasks;
using CoreSpotlight;
using Foundation;
using ObjCRuntime;
using UIKit;

namespace Microsoft.Maui.Controls.Compatibility.Platform.iOS
{
	internal class IOSAppLinks : IAppLinks
	{
		public async void DeregisterLink(IAppLinkEntry appLink)
		{
			if (string.IsNullOrWhiteSpace(appLink.AppLinkUri?.ToString()))
				throw new ArgumentNullException("AppLinkUri");
			await RemoveLinkAsync(appLink.AppLinkUri?.ToString());
		}

		public async void DeregisterLink(Uri uri)
		{
			if (string.IsNullOrWhiteSpace(uri?.ToString()))
				throw new ArgumentNullException(nameof(uri));
			await RemoveLinkAsync(uri.ToString());
		}

		public async void RegisterLink(IAppLinkEntry appLink)
		{
			if (string.IsNullOrWhiteSpace(appLink.AppLinkUri?.ToString()))
				throw new ArgumentNullException("AppLinkUri");
			await AddLinkAsync(appLink);
		}

		public async void DeregisterAll()

View on GitHub (pinned to f377ff1c5e)

Solutions

Set AppLinkEntry.AppLinkUri before calling DeregisterLink: `entry.AppLinkUri = new Uri("myapp://detail/42");`
Check the value before deregistering: `if (!string.IsNullOrWhiteSpace(entry.AppLinkUri?.ToString())) Application.Current.AppLinks.DeregisterLink(entry);`
Use the Uri overload DeregisterLink(Uri) if you already have the raw URI string.

Example fix

// before
var entry = new AppLinkEntry { Title = "Item" };
Application.Current.AppLinks.DeregisterLink(entry);

// after
var entry = new AppLinkEntry
{
    Title = "Item",
    AppLinkUri = new Uri($"myapp://item/{id}")
};
Application.Current.AppLinks.DeregisterLink(entry);

Defensive patterns

Strategy: validation

Validate before calling

if (appLink is null || string.IsNullOrWhiteSpace(appLink.AppLinkUri?.ToString()))
    return; // or handle missing URI gracefully
Application.Current.AppLinks.DeregisterLink(appLink);

Prevention

Always set AppLinkUri when constructing an AppLinkEntry intended for indexing/deregistration.
Centralize AppLinkEntry creation in a factory that validates AppLinkUri.
Store registered URIs in a local set so you only deregister what you registered.

When it happens

Trigger: Calling `Application.Current.AppLinks.DeregisterLink(appLinkEntry)` where `appLinkEntry.AppLinkUri` is null, an empty string, or whitespace. Occurs when an AppLinkEntry is constructed without setting AppLinkUri before deregistration.

Common situations: AppLinkEntry objects created at runtime from dynamic data where the URI field is optional. Serializing/deserializing AppLinkEntry across app launches where AppLinkUri was lost. Registering links conditionally but always attempting deregistration.

Related errors

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