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 Developer Forum for additional support.

App crashes at launch with JS bundle errors

Cause: JS bundle in system causes conflicts. Your app won'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.

   vega 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-vega    
     

   • If using NPM scripts in package.json:

     Copy code Copied to clipboard.

     npm run start:vega
     

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, rebuild your app with JS bundle in system disabled:

   Copy code Copied to clipboard.

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

App builds successfully but is not visible on device

Cause: 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>
   

App remains invisible after bringing to foreground

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

Solution:

Check for multiple running apps:

1. Press Ctrl+C in the terminal where 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:
   • 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

Build fails with "too many open files" error

Cause: Known issue with Watchman file watching system, which impacts Mac M1 users. Watchman is used by the Metro bundler.

Solution: Re-install Watchman:

brew reinstall watchman
watchman shutdown-server; watchman watch-del-all; watchman

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: Sep 30, 2025