dotnet/maui · error · NotImplementedException

The layout is not implemented

Error message

The layout is not implemented

What it means

Thrown as NotImplementedException by StructuredItemsViewRenderer.SelectListViewBase when the Layout switch does not match GridItemsLayout, LinearItemsLayout(Vertical), or LinearItemsLayout(Horizontal). The renderer only knows how to create a ListViewBase for those three layout configurations; any other ItemsLayout subclass falls through.

Source

Thrown at src/Compatibility/Core/src/Windows/CollectionView/StructuredItemsViewRenderer.cs:67

			else if (changedProperty.Is(StructuredItemsView.ItemsLayoutProperty))
			{
				UpdateItemsLayout();
			}
		}

		protected override ListViewBase SelectListViewBase()
		{
			switch (Layout)
			{
				case GridItemsLayout gridItemsLayout:
					return CreateGridView(gridItemsLayout);
				case LinearItemsLayout listItemsLayout when listItemsLayout.Orientation == ItemsLayoutOrientation.Vertical:
					return CreateVerticalListView(listItemsLayout);
				case LinearItemsLayout listItemsLayout when listItemsLayout.Orientation == ItemsLayoutOrientation.Horizontal:
					return CreateHorizontalListView(listItemsLayout);
			}

			throw new NotImplementedException("The layout is not implemented");
		}

		protected virtual void UpdateHeader()
		{
			if (ListViewBase == null)
			{
				return;
			}

			if (_currentHeader != null)
			{
				Element.RemoveLogicalChild(_currentHeader);
				_currentHeader = null;
			}

			var header = ItemsView.Header;

			switch (header)

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Use only GridItemsLayout or LinearItemsLayout (Vertical/Horizontal) with StructuredItemsView on WPF/Windows.
2. If a custom layout is needed, subclass StructuredItemsViewRenderer and override SelectListViewBase to handle it.
3. Check the Maui compatibility version — ensure the renderer version matches the Controls version for layout support.

Example fix

// before
itemsView.Layout = new CustomItemsLayout(); // not handled

// after — use a supported layout type
itemsView.Layout = new GridItemsLayout(2, ItemsLayoutOrientation.Vertical);

static bool IsSupportedLayout(ItemsLayout layout) =>
    layout is GridItemsLayout ||
    (layout is LinearItemsLayout linear &&
     (linear.Orientation == ItemsLayoutOrientation.Vertical ||
      linear.Orientation == ItemsLayoutOrientation.Horizontal));

When it happens

Trigger: Assigning a custom ItemsLayout subclass, or an ItemsLayout orientation/value not in the handled cases, to a StructuredItemsView (CollectionView/CarouselView). The switch has no default except the throw, so unhandled types always crash.

Common situations: Using a third-party or custom ItemsLayout; setting Layout to a new LinearItemsLayout with an unexpected Orientation value; or upgrading to a Maui version that adds a new ItemsLayout type the renderer hasn't been updated for.

Related errors

• Can't set CarouselView to position {carouselPosition}. Items
• Visible item not found
• Element must be a Page
• NavigationPage must have a root Page before being used. Eith
• {nameof(element)} must be of type {typeof(IndicatorView).Nam

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