Debug Runtime Issues

This page helps you resolve common issues when apps build successfully but fail during runtime execution. If you don't find a solution to your specific problem here, post an issue in the Developer Forum for additional support.

Metro server fails to start or crashes frequently

Cause: Port conflicts, corrupted cache, or system resource constraints.

Solution:

1. Clear the Metro cache:

   npx react-native start --reset-cache
   

2. Check for port conflicts and use a different port:

   npx react-native start --port 8082
   

3. Restart the Metro server with verbose logging:

   npx react-native start --verbose
   

4. If issues persist, restart your development machine to clear system resources.

The app builds successfully but isn't visible on the device

Cause: The app is running in the background or there are UI rendering issues.

Solution:

1. Check which app is currently in the foreground:

   Copy code Copied to clipboard.

    vlcm list
   

2. If your app is in the background, bring it to the foreground:

   Copy code Copied to clipboard.

   vlcm trigger-app foreground -i <instance_id>
   

3. Toggle between background and foreground to refresh:

   Copy code Copied to clipboard.

   vlcm trigger-app background -i <instance_id>
   vlcm trigger-app foreground -i <instance_id>
   

The app remains invisible after bringing to the foreground

Cause: Multiple apps running on the Metro server or UI code errors. Only one app can use the Metro server at a time.

Solution:

Check for multiple running apps:

1. Press Ctrl+C in the terminal where the Metro server is running to close it.

2. Stop the app:

   Copy code Copied to clipboard.

    vega device terminate-app
   

3. Restart the app:

   Copy code Copied to clipboard.

    vega device launch-app
   

Check for UI code errors:

1. Monitor the Metro server output for errors caused by incompatible React Native packages.

2. Fix the errors in your code. The Metro server automatically rebuilds the bundle after each change.

App crashes at launch with JavaScript bundle errors

Cause: A JavaScript bundle in the system causes conflicts. Your app doesn't appear on the device or in the vlcm list output. The log shows "Requiring unknown module" or "Property __d doesn't exist" errors.

Solution:

1. Capture the device logs:

   vega device start-log-stream --device <device name>
   

2. Launch your app using one of these commands:

   • If using Vega CLI:

     Copy code Copied to clipboard.

     react-native run-app  
     

   • If using NPM scripts in package.json:

     Copy code Copied to clipboard.

     npm run start:vega
     

3. Monitor the log stream for error patterns.

   The following examples show common errors related to this issue:

   "Requiring unknown module" error:

   Uncaught Error: Requiring unknown module "2827612701754778". If you are sure the module exists, try restarting Metro.
   

   "Property '__d' doesn't exist" error:

   E Volta:[VegaScript-Native] Exception occurred in MessageQueue::runAsync: 
   [Property '__d' doesn't exist
   ReferenceError: Property '__d' doesn't exist at global
   

4. Stop the Metro server by pressing Ctrl+C in the terminal where it's running.

5. Clear the Metro cache and restart:

   npx react-native start --reset-cache
   

6. Rebuild and relaunch your app.

   If the error persists, check for conflicting system bundles. See App crashes or shows blank screen due to system bundle issues for details.

App crashes or shows blank screen due to system bundle issues

Cause: System bundles are missing or misconfigured. The app may also have legacy flags that override the default bundle splitting behavior. A missing system bundle typically means the OS version on the device doesn't match the SDK version used to build the app.

Solution:

1. Run the following commands at the root of your app (where your main package.json is located) to clean caches and update dependencies:

   Step	npm	Yarn	PNPM
   Clean cache	npm cache clean --force	yarn cache clean --all	pnpm cache delete
   Reset Metro cache	npm start -- --reset-cache	yarn start -- --reset-cache	pnpm start -- --reset-cache
   Clean build artifacts	npm run clean	yarn clean	pnpm clean
   Update dependencies	npm update	yarn upgrade	pnpm update

2. Run the following command to verify if your app uses system bundles:

   vega exec vpt dump {path/to/vpkg} assets/raw/keplerscript-app-config.json > keplerscript-app-config.json
   

3. Open the keplerscript-app-config.json file.

4. Look for the "systemBundles: {" section.

5. Remove legacy bundle splitting flags from your project.

   If you previously opted out of bundle splitting, your project may still contain flags that prevent system bundles from working correctly. These flags aren't needed. SDK v0.20 and later enables bundle splitting by default.

   • In package.json, remove useSystemJsBundles from the "kepler" section.
   • In build scripts, remove --split-bundle false and --use-system-js-bundles from your build commands.

6. If the issue persists, verify that the OS version on your device matches the SDK version used to build the app. If they don't match, update the SDK and rebuild. For build instructions, see Build an App with Vega Studio.

App doesn't include system bundle entries after building

Cause: The app was built in debug mode. Debug builds don't create split bundles, so system bundle entries are only present in release builds.

Solution: Build and submit a release version of your app, not a debug version.

Related topics

• Run Your App
• Build an App with Vega Studio
• Fix Vega Studio Build Issues
• Detect Where the App Crash Originates
• Manage Files, Crash Reports, and Logs
• Fix Debugging Issues
• Resolve Fast Refresh Issues
• Troubleshoot Issues

---

Last updated: Mar 09, 2026