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:
-
Capture the device logs:
vega device start-log-stream --device <device name>
-
Launch your app using one of these commands:
- If using Kepler CLI:
react-native run-vega
- If using NPM scripts in package.json:
npm run start:vega
- If using Kepler CLI:
-
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
-
If you see these errors, rebuild your app with JS bundle in system disabled:
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:
-
Check which app is currently in the foreground:
vlcm list
- If your app is in the background, bring it to the foreground:
vlcm trigger-app foreground -i <instance_id>
- Toggle between background and foreground to refresh:
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:
-
Press Ctrl+C in the terminal where Metro server is running to close it.
- Stop the app:
vega device terminate-app
- Restart the app:
vega device launch-app
Check for UI code errors:
- Monitor the Metro server output for errors:
- Look for issues caused by incompatible React Native packages
- The Metro server displays errors as they occur
- 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:
- Clear Metro cache:
npx react-native start --reset-cache
- Check for port conflicts and use a different port:
npx react-native start --port 8082
- Restart Metro server with verbose logging:
npx react-native start --verbose
- If issues persist, restart your development machine to clear system resources.
Related topics
Last updated: Sep 30, 2025