Before you continue
Before submitting a bug report, please review our troubleshooting documentation at Troubleshoot Issues | Vega Troubleshooting
If you still want to file a bug report, please make sure to fill in all the details below and provide the necessary information.
NOTE: PLEASE ONLY REPORT A SINGLE BUG USING THIS TEMPLATE.
If you’re experiencing multiple issues, please file a separate report for each.
Bug Description
1. Summary
Carousel from @amazon-devices/kepler-ui-components (vertical orientation) renders items in wrong position when scroll direction reverses mid-scroll on real Vega/Kepler hardware.
Off-screen pre-rendered items queued for previous direction get committed to layout AFTER direction flip, landing on wrong side of viewport. Item order breaks visually — items that
should appear below appear on top (or vice versa). Not reproducible on simulator due to faster render times closing the race window.
App Name:
App Link on Amazon Appstore (found through Developer Console → Actions column in App List → View on Amazon.com):
Bug Severity
Select one that applies
- Impacts operation of app
- Blocks current development
- Improvement suggestion
- Issue with documentation (If selected, please share the doc link and describe the issue)
- Other
2. Steps to Reproduce
-
Render a vertical Carousel (@amazon-devices/kepler-ui-components) with ≥ 6 distinct items (more items than viewport height — buffer must be active).
-
Give each item a visually distinct prefix (e.g., numeric index 1., 2., …) so render order is observable in the recording.
-
Focus first item on a REAL Vega/Kepler device (not simulator).
-
Press and HOLD the DOWN key — fast scroll begins, Carousel buffers items ahead in scroll direction.
-
While items are still moving (mid-recycle), release DOWN and immediately press UP.
-
Observe rendered item order vs. expected numeric sequence.
-
Repeat opposite direction: HOLD UP, then immediately switch to DOWN.
-
Note: each Carousel item is itself a horizontal Carousel rendering complex tiles (images, focusable children, per-tile state). Nested Carousel + complex children is what makes
per-item render expensive enough to expose the race on real hardware.Triggering component: Carousel with orientation=“vertical”, maxToRenderPerBatch={5}, numOffsetItems={1}. Bug surfaces in Carousel’s layout commit path on direction change.
3. Observed Behavior
Explain what actually happened, noting any discrepancies or malfunctions.
After direction reversal mid-scroll on real hardware:
- Pre-rendered items queued for old direction get inserted on wrong side of viewport.
- Visual order breaks — e.g., sequence shows 5, 6, 3, 4, 7 instead of 3, 4, 5, 6, 7.
- Broken order persists until further scroll forces full re-layout. Sometimes self-corrects, sometimes not.
- Reproduces in BOTH directions (down→up and up→down).
- 100% reproducible on real device with key-repeat direction reversal.
- NOT reproducible on simulator — per-item render is extremely fast there, pending scheduled items drain before direction flips, race window closes.
- Carousel items are non-trivial composites (image tiles + text + focusable children + per-tile state), not simple primitives — per-item render cost is meaningful on real hardware, which
is precisely what keeps scheduled items in flight long enough to expose the race.
4. Expected Behavior
Describe what you expected the SDK to do under normal operation.
Items stay in correct logical order regardless of scroll direction or speed. Buffered/pre-rendered items always render in correct slot relative to viewport. Direction reversal should
invalidate or re-position pending scheduled items before commit to layout.
4.a Possible Root Cause & Temporary Workaround
Fill out anything you have tried. If you don’t know, N/A is acceptable
Suspected root cause: Race condition between (1) Carousel "schedule next N items in current scroll direction" pass and (2) direction-change handler. On real device, per-item render is
slow enough that items scheduled for old direction are still pending when direction flips — they commit to layout AFTER the flip without re-clamping to the correct buffer slot. On
simulator, render is fast enough that the queue drains before the flip, hiding the bug. No flush/cancel of pending items on direction change.
Workaround in use: Replaced Carousel with plain vertical ScrollView. Bug disappears. Trade-off: lose Carousel's recycling/virtualization, higher memory footprint, but only viable option
until Carousel is fixed.
- Each Carousel item in production renders a complex section (multiple tiles with images, focusable children, state subscriptions). This per-item cost is what makes the race observable
on device but invisible on simulator where rendering is near-instant.
5. Logs or crash report
(Please make sure to provide relevant logs as attachment)
No crash. Visual-only bug. Frame grabs attached showing misorder progression (mp4 not supported by form).
6. Environment
Please fill out the fields related to your bug below:
-
SDK Version:
Active SDK Version: 0.22.6620
Vega CLI Version: 1.2.18 -
App State:
Foreground -
@amazon-devices/kepler-ui-components: ^2.4.2
-
OS Information: Please ssh into the device via
vega exec vda shell(orkepler exec vda shellfor v0.21 and earlier) and copy the output fromcat /etc/os-releaseinto the answer section below. Note, if you don’t have a simulator running or device attached, the command will respond withvda: no devices/emulators foundNAME="OS" OE_VERSION="4.0.0" OS_MAJOR_VERSION="1" OS_MINOR_VERSION="1" RELEASE_ID="14" OS_VERSION="1.1" BRANCH_CODE="TV Ship day60" BUILD_DESC="OS 1.1 (TV Ship day60/4460)" BUILD_FINGERPRINT="4.0.227617.0(3072cab629675a74)/4460N:user-external/release-keys" BUILD_VARIANT="user-external" BUILD_TAGS="release-keys" BUILD_DATE="Fri Feb 20 16:02:43 UTC 2026" BUILD_TIMESTAMP="1771603363" VERSION_NUMBER="1401010446050"
7. Example Code Snippet / Screenshots / Screengrabs
Include any relevant code or component setup in React Native that can help reproduce the bug.
Annotated frame grabs attached (mp4 not supported). Items prefixed with
numeric index — misorder visible across frames.
// @amazon-devices/kepler-ui-components ^2.4.2
import { Carousel } from '@amazon-devices/kepler-ui-components';
<Carousel
data={items} // ≥ 6 distinct, ordered items
renderItem={renderItem}
keyProvider={keyExtractor}
getItemForIndex={getItemForIndex}
itemDimensions={itemDimensions}
orientation="vertical"
itemPadding={0}
maxToRenderPerBatch={5}
numOffsetItems={1}
/>
Repro requires:
- Real Vega/Kepler hardware (NOT simulator).
- Key-repeat (hold) input.
- Direction reversal while Carousel is mid-recycle.
- renderItem in real app returns a section composite (image tiles, focusable children, signal subscriptions) — not a primitive. Reproduction likely requires non-trivial render cost per
item, or artificial delay in renderItem, to widen the race window.
Additional Context
Any Additional Context you would like to provide?
Add any other relevant information, such as recent updates to the SDK, dependencies, or device OS that may affect the bug.
- Bug is hardware-only. Simulator testing misses it entirely due to faster per-item render. Suggest Amazon SDK test plans for Carousel include real-device direction-reversal scenario.
- Speed of direction reversal correlates with reproduction: faster reversal = more pending items = more visible misorder.
- Application data is static and ordered — bug is purely in Carousel layout/scheduling logic.
- Requesting either (a) Carousel invalidates/re-positions pending scheduled items on direction reversal before layout commit, or (b) exposed API to flush/cancel pending items on
direction change.
- Currently forced to use ScrollView workaround across all dynamic, long, vertically-scrolling views — losing the performance benefit Carousel was meant to provide.
