dotnet/maui · error · InvalidOperationException

This should never happen, please file a bug

Error message

This should never happen, please file a bug

What it means

Thrown by NavigationPageRenderer.InsertPageBefore when IndexOf(before) on PageController.InternalChildren returns -1, meaning the 'before' page is not present in the NavigationPage's logical children. This is an assertion-style guard: the navigation request references a page that the renderer's fragment stack and the NavigationPage's child list disagree on, indicating an internal state inconsistency. The message explicitly asks for a bug report.

Source

Thrown at src/Compatibility/Core/src/Android/AppCompat/NavigationPageRenderer.cs:560

			else if (e.PropertyName == NavigationPage.IconColorProperty.PropertyName)
				UpdateToolbar();
		}

		void DeviceInfoPropertyChanged(object sender, DisplayInfoChangedEventArgs e)
		{
			ResetToolbar();
		}

		void InsertPageBefore(Page page, Page before)
		{
			if (!_isAttachedToWindow)
				PushCurrentPages();

			UpdateToolbar();

			int index = PageController.InternalChildren.IndexOf(before);
			if (index == -1)
				throw new InvalidOperationException("This should never happen, please file a bug");

			Fragment fragment = FragmentContainer.CreateInstance(page);
			_fragmentStack.Insert(index, fragment);
		}

		void OnInsertPageBeforeRequested(object sender, NavigationRequestedEventArgs e)
		{
			InsertPageBefore(e.Page, e.BeforePage);
		}

		void OnPopped(object sender, NavigationRequestedEventArgs e)
		{
			e.Task = PopViewAsync(e.Page, e.Animated);
		}

		void OnPoppedToRoot(object sender, NavigationRequestedEventArgs e)
		{
			e.Task = PopToRootAsync(e.Page, e.Animated);

View on GitHub (pinned to f377ff1c5e)

Solutions

  1. Before calling InsertPageBefore, verify NavigationPage.NavigationStack contains the 'before' page and that it is not null.
  2. Avoid issuing InsertPageBefore while a push/pop animation is in flight; defer navigation until the previous operation's task completes.
  3. If using fragment restoration, set AllowFragmentRestore appropriately and rebuild the stack from the authoritative NavigationStack rather than relying on restored fragments.

Example fix

// before
navPage.InsertPageBefore(newPage, beforePage); // throws if beforePage not in stack

// after
if (navPage.NavigationStack.Contains(beforePage))
    navPage.InsertPageBefore(newPage, beforePage);
else
    await navPage.PushAsync(newPage);
Defensive patterns

Strategy: validation

Validate before calling

// Before InsertPageBefore, confirm 'before' is on the NavigationPage stack.
bool CanInsertBefore(NavigationPage nav, Page before)
{
    return before != null && nav.NavigationStack.Contains(before);
}

Try / catch

try
{
    navPage.InsertPageBefore(newPage, beforePage);
}
catch (InvalidOperationException ex) when (ex.Message.Contains("never happen"))
{
    // The 'before' page is not in the stack; refresh from the authoritative NavigationStack.
    Log.Error(nameof(NavigationPage), $"InsertPageBefore failed; '{beforePage}' not in stack.");
}

Prevention

When it happens

Trigger: Calling NavigationPage.InsertPageBefore with a 'before' page that was never pushed, already popped, or belongs to a different NavigationPage. Can also arise from a race where the page is removed concurrently, or after a fragment state restoration mismatch where InternalChildren and _fragmentStack diverge.

Common situations: Programmatic navigation logic that inserts before a stale page reference. Fragment restoration after process death where InternalChildren were not rebuilt. Concurrency between navigation events and collection modification. Known edge cases in older Forms versions around InsertPageBefore during animated transitions.

Related errors

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