What causes "Element must be a Page" in dotnet/maui?

Pass only a NavigationPage instance to NavigationPageRenderer.SetElement.

dotnet/maui · error · ArgumentException

Element must be a Page

Error message

Element must be a Page

What it means

Thrown as ArgumentException by NavigationPageRenderer.SetElement when the element is non-null and not a NavigationPage. The renderer is specifically for NavigationPage instances; passing any other VisualElement (ContentPage, TabbedPage, etc.) is a type mismatch.

Source

Thrown at src/Compatibility/Core/src/Windows/NavigationPageRenderer.cs:165

			child.Measure(constraint);
			var result = new Size(Math.Ceiling(child.DesiredSize.Width), Math.Ceiling(child.DesiredSize.Height));

			child.Width = oldWidth;
			child.Height = oldHeight;

			return new SizeRequest(result);
		}

		UIElement IVisualElementRenderer.GetNativeElement()
		{
			return null;
		}

		public void SetElement(VisualElement element)
		{
			if (element != null && !(element is NavigationPage))
				throw new ArgumentException("Element must be a Page", nameof(element));

			NavigationPage oldElement = Element;
			Element = (NavigationPage)element;

			if (Element != null && Element.CurrentPage is null)
				throw new InvalidOperationException(
					"NavigationPage must have a root Page before being used. Either call PushAsync with a valid Page, or pass a Page to the constructor before usage.");

			if (oldElement is INavigationPageController navigationPageController)
			{
				navigationPageController.PushRequested -= OnPushRequested;
				navigationPageController.PopRequested -= OnPopRequested;
				navigationPageController.PopToRootRequested -= OnPopToRootRequested;
				oldElement.InternalChildren.CollectionChanged -= OnChildrenChanged;
				oldElement.PropertyChanged -= OnElementPropertyChanged;
			}

			if (element != null)

View on GitHub (pinned to f377ff1c5e)

Solutions

Pass only a NavigationPage instance to NavigationPageRenderer.SetElement.
Check renderer registrations (ExportRenderer attributes) to ensure NavigationPage maps to NavigationPageRenderer.
Use the correct renderer type for the element (e.g., PageRenderer for ContentPage).

Example fix

// before
var renderer = new NavigationPageRenderer();
renderer.SetElement(contentPage); // wrong type

// after
var renderer = new NavigationPageRenderer();
renderer.SetElement(new NavigationPage(contentPage)); // correct

Defensive patterns

Strategy: type-guard

Validate before calling

if (element is NavigationPage || element == null)
    renderer.SetElement(element);

Type guard

static bool IsValidForNavigationPageRenderer(VisualElement element) => element is NavigationPage || element == null;

Prevention

Match each element type with its correct renderer via ExportRenderer attributes.
Never manually pass a non-NavigationPage to a NavigationPageRenderer.

When it happens

Trigger: Calling SetElement with a non-NavigationPage VisualElement on a NavigationPageRenderer instance. This can happen if the renderer registration is misconfigured or if SetElement is called manually with the wrong element type.

Common situations: Renderer registration mismatch (wrong ExportRenderer attribute), manually creating a NavigationPageRenderer and passing a ContentPage, or platform-specific code that incorrectly assigns element types.

Related errors

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