dotnet/maui · error · ArgumentException

Element must be of type Frame

Error message

Element must be of type Frame

What it means

FrameRenderer.SetElement uses an `as` cast and throws ArgumentException if the result is null (element is not a Frame). Unlike the null-then-is pattern used by other fast renderers, FrameRenderer does not separately guard against a null element, so a null element would surface as the same 'must be of type Frame' message.

Source

Thrown at src/Compatibility/Core/src/Android/FastRenderers/FrameRenderer.cs:79

				_element?.SendViewInitialized(Control);
			}
		}

		VisualElement IVisualElementRenderer.Element => Element;
		AView IVisualElementRenderer.View => this;

		SizeRequest IVisualElementRenderer.GetDesiredSize(int widthMeasureSpec, int heightMeasureSpec)
		{
			Context context = Context;
			return new SizeRequest(new Size(context.ToPixels(20), context.ToPixels(20)));
		}

		void IVisualElementRenderer.SetElement(VisualElement element)
		{
			var frame = element as Frame;
			if (frame == null)
				throw new ArgumentException("Element must be of type Frame");
			Element = frame;
			_motionEventHelper.UpdateElement(frame);

			if (!string.IsNullOrEmpty(Element.AutomationId))
				ContentDescription = Element.AutomationId;
		}

		void IVisualElementRenderer.SetLabelFor(int? id)
		{
			if (_defaultLabelFor == null)
				_defaultLabelFor = ViewCompat.GetLabelFor(this);

			ViewCompat.SetLabelFor(this, (int)(id ?? _defaultLabelFor));
		}

		VisualElementTracker IVisualElementRenderer.Tracker => _visualElementTracker;

		void IVisualElementRenderer.UpdateLayout()

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Register FrameRenderer only for Frame (or a Frame subclass).
2. Guard against passing null — the renderer lacks an explicit ArgumentNullException path, so callers must supply a non-null Frame.
3. Prefer the MAUI handler over the compatibility renderer where possible.

Example fix

// before
var frame = element as Frame;
if (frame == null)
    throw new ArgumentException("Element must be of type Frame");
// after — also reject null explicitly
if (element == null)
    throw new ArgumentNullException(nameof(element));
if (element is not Frame frame)
    throw new ArgumentException("Element must be of type Frame", nameof(element));

if (element is null) throw new ArgumentNullException(nameof(element));
if (element is not Frame) throw new ArgumentException("Expected Frame.", nameof(element));
((IVisualElementRenderer)renderer).SetElement(element);

static bool IsFrame(VisualElement e) => e is Frame;

When it happens

Trigger: SetElement invoked with an element that is not a Frame (or, with the same message, a null element because the `as` yields null and there is no dedicated ArgumentNullException here).

Common situations: Wrong ExportRenderer registration for FrameRenderer; subclassing FrameRenderer and binding it to a non-Frame control; passing null during teardown paths.

Related errors

• {nameof(element)} must be of type {nameof(Button)}
• Element is not of type " + typeof(Image)
• Element must be of type Label
• {nameof(element)} must be of type {typeof(IndicatorView).Nam
• {nameof(element)} must be of type {typeof(ItemsView).Name}

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