Troubleshoot the Meta VR Layout SDK
Updated: Oct 30, 2026
Use these checks when a spatial window crashes, renders incorrectly, or does not appear. Start by confirming that your app follows the
Layout SDK setup.
The app crashes at startup
For Compose, call SpatialScene from an activity’s setContent block and keep every SpatialWindow within it. For React Native, keep every SpatialWindow within SpatialSceneProvider.
A spatial window is black or blank
Check the
window background color. Use
WindowModifier.background(color) in Compose or
windowBackgroundColor in React Native to set an explicit opaque color; otherwise, the window uses the app theme’s
android:windowBackground. Transparency is not supported.
Make the content root fill the window’s declared dimensions. Compose uses the SDK default of 256 dp on each axis when no size is supplied. React Native requires windowWidth and windowHeight.
A spatial window does not appear
Verify the Horizon OS version and framework spatial-support state. On releases earlier than v207, the SDK uses fallback behavior instead of placing spatial windows. Check the window’s key or label, priority, and fallback behavior. Restart the device to clear stale state, then use
Meta Spatial Simulator to help isolate device-specific behavior.
React Native reports a startup or red error screen
Keep the JavaScript package and native Maven artifact on matching major and minor versions. Import the Meta VR SDK BOM and let React Native link the native package automatically.
npm list @metavr/layout-compat @metavr/layout-window-compat