dotnet/maui · error · ArgumentException

Pin must have a Label to be added to a map

Error message

Pin must have a Label to be added to a map

What it means

The Map control validates pins added to its Pins collection. When a Pin is added whose Label is null, PinsOnCollectionChanged throws ArgumentException because map platforms (iOS Maps, Android Google Maps, etc.) require a non-null label to display and identify a pin annotation. Without a label the pin is unusable on all native map renderers.

Source

Thrown at src/Controls/Maps/src/Map.cs:231

			{
				throw new ArgumentNullException(nameof(visibleRegion));
			}

			if (_visibleRegion == visibleRegion)
			{
				return;
			}

			OnPropertyChanging(nameof(VisibleRegion));
			_visibleRegion = visibleRegion;
			OnPropertyChanged(nameof(VisibleRegion));
		}

		void PinsOnCollectionChanged(object? sender, NotifyCollectionChangedEventArgs e)
		{
			if (e.NewItems is not null && e.NewItems.Cast<Pin>().Any(pin => pin.Label is null))
			{
				throw new ArgumentException("Pin must have a Label to be added to a map");
			}

			Handler?.UpdateValue(nameof(IMap.Pins));
		}

		void MapElementsCollectionChanged(object? sender, NotifyCollectionChangedEventArgs e)
		{
			Handler?.UpdateValue(nameof(IMap.Elements));
			if (e.NewItems is not null)
			{
				foreach (MapElement item in e.NewItems)
				{
					item.PropertyChanged += MapElementPropertyChanged;
				}
			}

			if (e.OldItems is not null)
			{

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Always set Pin.Label before adding it to the Map: `new Pin { Label = "My Location", Location = loc }`.
2. When using ItemsSource and ItemTemplate, ensure the Label binding target is non-null: `Label="{Binding Name}"` where Name is guaranteed.
3. Filter or default null labels before adding pins: `Label = place.Name ?? "Unknown"`.
4. If populating from async data, add the pin only after the label is resolved.

Example fix

// before
map.Pins.Add(new Pin
{
    Location = new Location(47.6, -122.3)
    // Label missing
});

// after
map.Pins.Add(new Pin
{
    Label = "Seattle",
    Location = new Location(47.6, -122.3)
});

// Validate before adding to Map.Pins
var pin = new Pin { Location = loc };
if (string.IsNullOrEmpty(pin.Label))
    pin.Label = "Unknown";
map.Pins.Add(pin);

// Or filter a collection
foreach (var p in pinList.Where(p => !string.IsNullOrEmpty(p.Label)))
    map.Pins.Add(p);

static bool HasValidLabel(Pin pin) => !string.IsNullOrEmpty(pin.Label);

When it happens

Trigger: Adding a Pin to `Map.Pins` (or assigning ItemsSource that generates pins) where at least one Pin has a null Label. Occurs during `map.Pins.Add(new Pin { Location = ... })` without setting Label, or when a data-binding for Label resolves to null.

Common situations: Binding Pins to a collection where the label property is nullable or occasionally null. Creating pins from geocoding results where the place name is missing. ItemsSource data templates that don't bind Label. Programmatic pin creation from API responses with optional name fields.

Related errors

• EnumPicker: EnumType property must be enumeration type
• EnumPicker: EnumType property must be enumeration type
• Value is an invalid value for {property.PropertyName}
• RootComponent requires a value for its Selector property, bu
• RootComponent requires a value for its ComponentType propert

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