dotnet/maui · error · InvalidOperationException

Active Shell Item not set. Have you added any Shell Items to

Error message

Active Shell Item not set. Have you added any Shell Items to your Shell?

What it means

Thrown by the iOS ShellRenderer.SetupCurrentShellItem when Shell.CurrentItem is null. The Shell is the root visual element; its CurrentItem must be a valid ShellItem (flyout item, tab, or bottom-nav item). If no ShellItem has been added or CurrentItem is null, the renderer cannot set up the flyout content.

Source

Thrown at src/Controls/src/Core/Compatibility/Handlers/Shell/iOS/ShellRenderer.cs:367

				UpdateBackgroundColor();
				UpdateFlowDirection();
			}
		}

		protected virtual void UpdateBackgroundColor()
		{
			var color = Shell.BackgroundColor?.ToPlatform();
			if (color == null)
				color = Microsoft.Maui.Platform.ColorExtensions.BackgroundColor;

			FlyoutRenderer.View.BackgroundColor = color;
		}

		void SetupCurrentShellItem()
		{
			if (Shell.CurrentItem == null)
			{
				throw new InvalidOperationException("Active Shell Item not set. Have you added any Shell Items to your Shell?");
			}
			else if (Shell.CurrentItem.CurrentItem == null)
			{
				throw new InvalidOperationException($"Content not found for active {Shell.CurrentItem}. Title: {Shell.CurrentItem.Title}. Route: {Shell.CurrentItem.Route}.");
			}
			else if (_currentShellItemRenderer == null)
			{
				OnCurrentItemChanged();
			}
		}

		bool IViewHandler.HasContainer { get => false; set { } }

		object IViewHandler.ContainerView => null;

		IView IViewHandler.VirtualView => Element;

		object IElementHandler.PlatformView => NativeView;

View on GitHub (pinned to f377ff1c5e)

Solutions

1. Ensure at least one ShellItem (or FlyoutItem/Tab) exists in the Shell before it is rendered.
2. Add items in the Shell constructor or OnInitialized override, before the page is displayed.
3. Set Shell.CurrentItem explicitly after adding items programmatically.
4. Verify XAML Shell structure has valid ShellItem children with ShellContent.
5. Check that Routing.RegisterRoute calls and DataTemplates resolve correctly.

Example fix

// before
public partial class AppShell : Shell
{
    public AppShell()
    {
        InitializeComponent();
        // items added later — too late for iOS renderer init
    }
}

// after
public partial class AppShell : Shell
{
    public AppShell()
    {
        InitializeComponent();
        Items.Add(new FlyoutItem
        {
            Title = "Home",
            Items = { new ShellContent { ContentTemplate = new DataTemplate(() => new HomePage()) } }
        });
        CurrentItem = Items[0];
    }
}

// Verify Shell has a current item before rendering
if (Shell.CurrentItem == null)
    throw new InvalidOperationException("Shell has no active ShellItem.");

public static bool ShellHasCurrentItem(Shell shell)
    => shell?.CurrentItem != null;

When it happens

Trigger: At line 367: `if (Shell.CurrentItem == null) throw`. SetupCurrentShellItem is called during Shell initialization on iOS. Triggered when: (1) Shell has zero ShellItem children; (2) Shell.CurrentItem was explicitly set to null; (3) ShellItem auto-selection failed; (4) items were added after rendering started.

Common situations: 1) App with `<Shell>` but no `<ShellItem>`/`<Tab>`/`<FlyoutItem>` children. 2) Shell items added dynamically after the Shell is already displayed. 3) ShellContent/ShellItem DataTemplates that failed to resolve, leaving the items collection effectively empty. 4) Routing configuration that prevents item auto-selection.

Related errors

• Content not found for active {ShellItem}. Title: {ShellItem.
• Reuse of the Shell Renderer is not supported
• Content not found for active {Shell.CurrentItem}. Title: {Sh
• Content not found for active {ShellSection}. Title: {ShellSe
• view

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