{"record":{"id":"45ccbac8203aeb56","repo":"dotnet/maui","slug":"can-t-set-carouselview-to-position-carouselpositi","errorCode":null,"errorMessage":"Can't set CarouselView to position {carouselPosition}. ItemsSource has {itemCount} items.","messagePattern":"Can't set CarouselView to position (.+?)\\. ItemsSource has (.+?) items\\.","errorType":"exception","errorClass":"IndexOutOfRangeException","httpStatus":null,"severity":"error","filePath":"src/Compatibility/Core/src/Android/CollectionView/CarouselViewRenderer.cs","lineNumber":534,"sourceCode":"\t\t{\n\t\t\tif (!_initialized)\n\t\t\t{\n\t\t\t\t_carouselViewLoopManager.AddPendingScrollTo(new ScrollToRequestEventArgs(Carousel.Position, -1, Microsoft.Maui.Controls.ScrollToPosition.Center, false));\n\t\t\t}\n\n\t\t\tvar itemCount = ItemsViewAdapter?.ItemsSource.Count ?? 0;\n\t\t\tvar carouselPosition = Carousel.Position;\n\n\t\t\tif (itemCount == 0)\n\t\t\t{\n\t\t\t\t//we are trying to set a position but our Collection doesn't have items still\n\t\t\t\t_oldPosition = carouselPosition;\n\t\t\t\treturn;\n\t\t\t}\n\n\n\t\t\tif (carouselPosition >= itemCount || carouselPosition < 0)\n\t\t\t\tthrow new IndexOutOfRangeException($\"Can't set CarouselView to position {carouselPosition}. ItemsSource has {itemCount} items.\");\n\n\t\t\tif (carouselPosition == _gotoPosition)\n\t\t\t\t_gotoPosition = -1;\n\n\t\t\tif (_noNeedForScroll)\n\t\t\t{\n\t\t\t\t_noNeedForScroll = false;\n\t\t\t\treturn;\n\t\t\t}\n\n\t\t\tvar centerPosition = GetCarouselViewCurrentIndex(carouselPosition);\n\t\t\tif (_gotoPosition == -1 && !Carousel.IsDragging && !Carousel.IsScrolling && centerPosition != carouselPosition)\n\t\t\t{\n\t\t\t\t_gotoPosition = carouselPosition;\n\n\t\t\t\tCarousel.ScrollTo(carouselPosition, position: Microsoft.Maui.Controls.ScrollToPosition.Center, animate: Carousel.AnimatePositionChanges);\n\t\t\t}\n\t\t\tSetCurrentItem(carouselPosition);","sourceCodeStart":516,"sourceCodeEnd":552,"githubUrl":"https://github.com/dotnet/maui/blob/f377ff1c5ee04d334d8a925f50c83a6b7afddf03/src/Compatibility/Core/src/Android/CollectionView/CarouselViewRenderer.cs#L516-L552","documentation":"Thrown by CarouselViewRenderer.UpdateFromPosition when Carousel.Position is greater than or equal to the current ItemsSource count, or is negative. The renderer validates the requested position against the live item count before scrolling the underlying Android CarouselRecyclerView; an out-of-range position would index past the adapter's bounds.","triggerScenarios":"Binding Carousel.Position to a value that exceeds the number of items. Replacing or clearing ItemsSource while Position retains a stale value. Programmatic position set before items are loaded. Race between ItemsSource collection change and Position property update.","commonSituations":"Restoring Carousel.Position from persisted state after the items source was reset. Two-way binding Position to a ViewModel property that gets set to an item index that no longer exists. Concurrency between a web request populating items and a position restore.","solutions":["Clamp the Position value to the valid range [0, items.Count - 1] before setting it, and reset Position to 0 when ItemsSource is replaced or cleared.","Set ItemsSource before setting Position, and ensure at least one item exists before assigning a non-zero position.","If restoring Position from persisted state, defer the restore until after ItemsSource is populated and validated."],"exampleFix":"// before\ncarousel.ItemsSource = newItems;\ncarousel.Position = savedPosition; // throws if savedPosition >= newItems.Count\n\n// after\ncarousel.ItemsSource = newItems;\ncarousel.Position = Math.Min(savedPosition, Math.Max(0, newItems.Count - 1));","handlingStrategy":"validation","validationCode":"// Clamp Position to a valid range before assigning.\nstatic int ClampPosition(int desired, int itemCount) =>\n    itemCount <= 0 ? 0 : Math.Max(0, Math.Min(desired, itemCount - 1));\n// Usage:\ncarousel.Position = ClampPosition(savedPosition, ((IList)carousel.ItemsSource)?.Count ?? 0);","typeGuard":null,"tryCatchPattern":"try\n{\n    carousel.Position = savedPosition;\n}\ncatch (IndexOutOfRangeException ex) when (ex.Message.Contains(\"CarouselView\"))\n{\n    carousel.Position = 0;\n    Log.Warn(nameof(CarouselView), \"Saved position out of range; reset to 0.\");\n}","preventionTips":["Reset Position to 0 whenever ItemsSource is cleared or replaced.","Defer restoring a persisted Position until ItemsSource is populated and its count is known.","Clamp Position values in the ViewModel setter before propagating to the CarouselView.","Avoid programmatic ScrollTo/Position changes while the source is empty."],"tags":["android","carouselview","position","itemssource","collectionview"],"backgroundTag":null,"analyzedSha":"f377ff1c5ee04d334d8a925f50c83a6b7afddf03","analyzedAt":"2026-08-13T14:26:18.069Z","schemaVersion":2},"datasetVersion":"2026-08-13T19:17:28.613Z"}