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.

App crashes at launch with JS bundle errors

Cause: JS bundle in the system causes conflicts. Your app doesn't appear on the device or in the vlcm list output. You see either "Requiring unknown module" or "Property __d doesn't exist" errors.

Solution:

1. Capture the device logs:

   Copy code Copied to clipboard.

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

2. Launch your app using one of these commands:

   • If using Kepler CLI:

     Copy code Copied to clipboard.

     react-native run-kepler   
     

   • If using NPM scripts in package.json:

     Copy code Copied to clipboard.

     npm run start:kepler
     

3. Monitor the log stream for error patterns:

   "Requiring unknown module" error example:

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

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

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

4. If you see these errors, disable the JS bundle system and rebuild your app:

   Copy code Copied to clipboard.

    react-native build-kepler --use-system-js-bundles false
   

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 foreground

Cause: Multiple apps running on 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.

    kepler device terminate-app
   

3. Restart the app:

   Copy code Copied to clipboard.

    kepler device launch-app
   

Check for UI code errors:

1. Monitor the Metro server output for errors:
   • Look for issues caused by incompatible React Native packages
   • The Metro server displays errors as they occur
2. Fix the errors in your code:
   • The Metro server automatically rebuilds the bundle after each change
   • Once you fix the error, the Metro server creates a bundle

Metro server fails to start or crashes frequently

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

Solution:

1. Clear 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 Metro server with verbose logging:

   npx react-native start --verbose
   

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

Related topics

• Run Your App
• Build an App with Vega Studio

---

Last updated: Nov 14, 2025