What causes "throw new ArgumentOutOfRangeException();" in dotnet/maui?

Avoid raising CollectionChanged on the Effects collection directly — use the Effects.Add/Remove API.

dotnet/maui · error · ArgumentOutOfRangeException

throw new ArgumentOutOfRangeException();

Error message

throw new ArgumentOutOfRangeException();

What it means

Thrown as the default case of the switch over NotifyCollectionChangedEventArgs.Action in EffectsOnCollectionChanged. The switch handles Add, Move, Remove, Replace, Reset explicitly; any other enum value (which should not exist in the standard NotifyCollectionChangedAction enum) hits the default and throws ArgumentOutOfRangeException with no message. This is a defensive invariant guard.

Source

Thrown at src/Controls/src/Core/Element/Element.cs:959

					break;
				case NotifyCollectionChangedAction.Reset:
					if (e.NewItems != null)
					{
						foreach (Effect effect in e.NewItems)
						{
							AttachEffect(effect);
						}
					}
					if (e.OldItems != null)
					{
						foreach (Effect effect in e.OldItems)
						{
							effect.ClearEffect();
						}
					}
					break;
				default:
					throw new ArgumentOutOfRangeException();
			}
		}

		internal INameScope GetNameScope()
		{
			if (!RuntimeFeature.AreNamescopesSupported)
				throw new NotSupportedException("Namescopes are not supported. Please enable the feature switch 'Microsoft.Maui.RuntimeFeature.AreNamescopesSupported' to keep using namescopes.");

			var element = this;
			do
			{
				var ns = NameScope.GetNameScope(element);
				if (ns != null)
					return ns;
			} while ((element = element.RealParent) != null);
			return null;
		}

View on GitHub (pinned to f377ff1c5e)

Solutions

Avoid raising CollectionChanged on the Effects collection directly — use the Effects.Add/Remove API.
If wrapping the collection, ensure NotifyCollectionChangedEventArgs.Action is always one of Add/Move/Remove/Replace/Reset.
Inspect the source raising the event; this error indicates a logic bug upstream, not a configuration issue.

Example fix

// before — raising with an invalid action
effectsCollection.CollectionChanged?.Invoke(this,
    new NotifyCollectionChangedEventArgs((NotifyCollectionChangedAction)999));
// after — use the public API
element.Effects.Add(myEffect);

Defensive patterns

Strategy: try-catch

Validate before calling

// Not applicable at the caller boundary; this guards an internal invariant.
// Validate upstream: only raise CollectionChanged with known NotifyCollectionChangedAction values.

Type guard

static bool IsValidAction(NotifyCollectionChangedAction a) =>
    a == NotifyCollectionChangedAction.Add ||
    a == NotifyCollectionChangedAction.Move ||
    a == NotifyCollectionChangedAction.Remove ||
    a == NotifyCollectionChangedAction.Replace ||
    a == NotifyCollectionChangedAction.Reset;

Try / catch

// Internal framework code; callers should not raise events on the Effects collection.
// If wrapping, validate Action before raising.

Prevention

Use the Effects.Add/Remove API instead of raising CollectionChanged manually.
Validate NotifyCollectionChangedEventArgs.Action before forwarding events.
Avoid casting arbitrary integers to NotifyCollectionChangedAction.

When it happens

Trigger: A custom collection or external code raises a CollectionChanged event on the Element.Effects collection with an Action value outside the known enum, or casts an arbitrary integer to NotifyCollectionChangedAction. Extremely unlikely under normal MAUI usage; indicates a corrupted or non-standard collection event.

Common situations: Third-party collection wrappers forwarding malformed change notifications; reflection-based manipulation of the Effects collection; a bug in a custom ObservableCollection subclass raising events with invalid Action values.

Related errors

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