dotnet/maui · error · IndexOutOfRangeException

Can't set CarouselView to position {carouselPosition}. Items

Error message

Can't set CarouselView to position {carouselPosition}. ItemsSource has {ItemCount} items.

What it means

Thrown as IndexOutOfRangeException by CarouselViewRenderer.UpdateFromPosition when CarouselView.Position is set to a value outside [0, ItemCount). The renderer enforces that the position must map to a real item in the bound ItemsSource collection before it attempts to display it.

Source

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

		}

		[PortHandler]
		void UpdateFromCurrentItem()
		{
			var currentItemPosition = GetItemPositionInCarousel(CarouselView.CurrentItem);
			CarouselView.ScrollTo(currentItemPosition, position: ScrollToPosition.Center, animate: CarouselView.AnimateCurrentItemChanges);
		}

		[PortHandler]
		void UpdateFromPosition()
		{
			if (CollectionViewSource == null)
				return;

			var carouselPosition = CarouselView.Position;

			if (carouselPosition >= ItemCount || carouselPosition < 0)
				throw new IndexOutOfRangeException($"Can't set CarouselView to position {carouselPosition}. ItemsSource has {ItemCount} items.");

			SetCarouselViewCurrentItem(carouselPosition);
		}

		[PortHandler]
		void SetCarouselViewPosition(int position)
		{
			if (ItemCount == 0)
			{
				return;
			}

			if (!IsValidPosition(position))
				return;

			var currentPosition = CarouselView.Position;

			if (currentPosition != position)

View on GitHub (pinned to f377ff1c5e)

Solutions

Clamp Position to [0, ItemsSource.Count - 1] before or immediately after updating ItemsSource.
Reset Position to 0 when replacing ItemsSource with a new collection.
Ensure any data-bound Position property is revalidated when the item count changes.

Example fix

// before
carouselView.ItemsSource = newList; // Position may still be 5

// after
carouselView.Position = 0;
carouselView.ItemsSource = newList;
// or clamp: carouselView.Position = Math.Min(carouselView.Position, newList.Count - 1);

Defensive patterns

Strategy: validation

Validate before calling

if (carouselView.Position < 0 || carouselView.Position >= items.Count)
    carouselView.Position = 0;

Prevention

Reset or clamp CarouselView.Position whenever ItemsSource is replaced.
Ensure data-bound Position properties are revalidated on collection changes.

When it happens

Trigger: Setting CarouselView.Position to an index >= ItemCount or < 0. Common when ItemsSource is replaced with a smaller collection while Position retains its old value, or when Position is data-bound to a model property that hasn't been clamped.

Common situations: Replacing the ItemsSource with a shorter list without resetting Position; data-binding Position to a 1-based or off-by-one index; clearing ItemsSource while Position was non-zero.

Related errors

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