What causes "Visible item not found" in dotnet/maui?

Delay setting Position until after the ItemsSource has been rendered (e.g., on the next dispatcher tick or after the ListView Loaded event).

dotnet/maui · error · InvalidOperationException

Visible item not found

Error message

Visible item not found

What it means

Thrown as InvalidOperationException by CarouselViewRenderer.SetCarouselViewCurrentItem when GetItem(carouselPosition) does not return an ItemTemplateContext. This means the position passed validation (0 <= pos < ItemCount) but the item at that position has not yet been materialized/templated by the underlying list virtualization.

Source

Thrown at src/Compatibility/Core/src/Windows/CollectionView/CarouselViewRenderer.cs:414

			if (!IsValidPosition(position))
				return;

			var currentPosition = CarouselView.Position;

			if (currentPosition != position)
			{
				CarouselView.SetValueFromRenderer(CarouselView.PositionProperty, position);
			}
		}

		[PortHandler]
		void SetCarouselViewCurrentItem(int carouselPosition)
		{
			if (!IsValidPosition(carouselPosition))
				return;

			if (!(GetItem(carouselPosition) is ItemTemplateContext itemTemplateContext))
				throw new InvalidOperationException("Visible item not found");

			var item = itemTemplateContext.Item;
			CarouselView.SetValueFromRenderer(CarouselView.CurrentItemProperty, item);
		}

		[PortHandler]
		bool IsValidPosition(int position)
		{
			if (ItemCount == 0)
				return false;

			if (position < 0 || position >= ItemCount)
				return false;

			return true;
		}

		[PortHandler]

View on GitHub (pinned to f377ff1c5e)

Solutions

Delay setting Position until after the ItemsSource has been rendered (e.g., on the next dispatcher tick or after the ListView Loaded event).
Use CarouselView.ScrollTo with ScrollToPosition instead of setting Position directly during initialization.
Ensure the DataTemplate for items is registered before items are loaded.

Example fix

// before
carouselView.ItemsSource = items;
carouselView.Position = 3; // throws: item not yet materialized

// after — defer until loaded
carouselView.ItemsSource = items;
carouselView.Loaded += (s, e) =>
{
    carouselView.Position = 3;
};

Defensive patterns

Strategy: validation

Validate before calling

if (carouselView.ItemCount > 0 && position < carouselView.ItemCount)
{
    carouselView.Position = position;
}

Try / catch

try
{
    carouselView.Position = desiredPosition;
}
catch (InvalidOperationException ex) when (ex.Message.Contains("Visible item not found"))
{
    // item not yet materialized; defer to next layout cycle

Prevention

Set Position after the CarouselView has rendered its items (e.g., after Loaded).
Avoid setting Position synchronously during ItemsSource assignment.

When it happens

Trigger: The position is valid but the underlying ListViewBase has not yet created the container/item template context for that index — e.g., immediately after ItemsSource changes, during fast scrolling, or when virtualization defers container generation.

Common situations: Setting CarouselView.Position programmatically right after binding a new ItemsSource, before the UI has had a render pass. Also occurs during rapid Position changes or when the list is still loading.

Related errors

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