What causes "The view must inherit from VisualElement." in PrismLibrary/Prism?

Make sure the type registered for the region is a MAUI Page, ContentView, Layout or other VisualElement subclass, not the ViewModel.

PrismLibrary/Prism · error · UpdateRegionsException

The view must inherit from VisualElement.

Error message

The view must inherit from VisualElement.

What it means

Region.InnerAdd throws UpdateRegionsException when a view added to a region does not derive from VisualElement (the MAUI base class for anything with visual layout). Regions track, name, activate and deactivate views, and all of that bookkeeping requires a VisualElement. Any non-VisualElement object passed to IRegion.Add is rejected immediately.

Solutions

Make sure the type registered for the region is a MAUI Page, ContentView, Layout or other VisualElement subclass, not the ViewModel.
Check your RegisterForRegionNavigation / RegisterForNavigation<T> registration: T must be a VisualElement-derived view.
If you need a ViewModel in the region, use ViewModelLocator (ViewModelLocator.AutowireViewModel) on a VisualElement view rather than adding the ViewModel itself.
Wrap non-visual content in a ContentView/ContentPage that hosts it before adding to the region.

Example fix

// before
region.Add(myViewModel);

// after
var view = new MyContentView(); // MyContentView : ContentView
ViewModelLocator.SetAutowireViewModel(view, true);
region.Add(view);

Defensive patterns

Strategy: type-guard

Validate before calling

if (view is not VisualElement) throw new InvalidOperationException($"Cannot add {view?.GetType().Name} to region: must be a VisualElement");

Type guard

static bool IsValidRegionView(object v) => v is Microsoft.Maui.Controls.VisualElement;

Try / catch

try { region.Add(view); } catch (UpdateRegionsException ex) { logger.LogError(ex, "View is not a VisualElement"); }

Prevention

Always register view types (VisualElement subclasses) for region navigation, never ViewModels
Use ViewModelLocator autowiring instead of adding ViewModels directly
Add a unit test asserting registered region view types derive from VisualElement

When it happens

Trigger: Calling region.Add(someObject) or region.Add(someObject, "name") where someObject is not a Microsoft.Maui.Controls.VisualElement (e.g. a plain ViewModel, a string, or a non-visual service object).

Common situations: Registering ViewModels instead of Views for region navigation; registering a plain class as a view; MAUI bindings/registration mistakes where the container resolves the wrong type; porting WPF Prism code where objects that were not UIElement were tolerated by custom adapters.

Understand the failure class

Background: Type mismatch errors: IllegalArgumentException, TypeError and type guards across 150 open-source libraries — this error's family across 150 libraries.

Related errors

AI-assisted analysis of PrismLibrary/Prism@358118cd64 (2026-09-15). Data as JSON: /api/errors/faaca9b9ec9420a6. Report an issue: GitHub.

Appendix: source

Thrown at src/Maui/Prism.Maui/Navigation/Regions/Region.cs:267

    /// <summary>
    /// Adds a new view to the region.
    /// </summary>
    /// <param name="view">The view to add.</param>
    /// <param name="viewName">The name of the view. This can be used to retrieve it later by calling <see cref="IRegion.GetView"/>.</param>
    /// <param name="createRegionManagerScope">When <see langword="true"/>, the added view will receive a new instance of <see cref="IRegionManager"/>, otherwise it will use the current region manager for this region.</param>
    /// <returns>The <see cref="IRegionManager"/> that is set on the view if it is a <see cref="VisualElement"/>.</returns>
    public virtual IRegionManager Add(object view, string viewName, bool createRegionManagerScope)
    {
        IRegionManager manager = createRegionManagerScope ? RegionManager.CreateRegionManager() : RegionManager;
        InnerAdd(view, viewName, manager);
        return manager;
    }

    private void InnerAdd(object view, string viewName, IRegionManager scopedRegionManager)
    {
        if (view is not VisualElement visualElement)
        {
            throw new UpdateRegionsException("The view must inherit from VisualElement.");
        }

        if (ItemMetadataCollection.FirstOrDefault(x => x.Item == view) != null)
        {
            throw new InvalidOperationException(Resources.RegionViewExistsException);
        }

        var itemMetadata = new ItemMetadata(visualElement);
        if (!string.IsNullOrEmpty(viewName))
        {
            if (ItemMetadataCollection.FirstOrDefault(x => x.Name == viewName) != null)
            {
                throw new InvalidOperationException(string.Format(CultureInfo.InvariantCulture, Resources.RegionViewNameExistsException, viewName));
            }
            itemMetadata.Name = viewName;
        }

        Xaml.RegionManager.SetRegionManager(visualElement, scopedRegionManager);

View on GitHub (pinned to 358118cd64)