Having issues with system bundles (also known as JS Bundles in System or bundle splitting)? This guide covers how to verify your app is using system bundles, how to fix common issues, and how to debug crashes related to bundle splitting.
Steps to success
Run these commands at the root of your app (where your main package.json is located).
Update npm packages for app (if using npm):
npm cache clean --force # clears the global npm cache
npm start -- --reset-cache # clears metro cache (double dash forwards extra arguments)
npm run clean # this assumes that you have a "clean" script in your package.json
npm update # pulls the latest version of your app's dependencies
Corresponding commands for Yarn:
yarn cache clean --all
yarn start -- --reset-cache # double dash forwards extra arguments
yarn clean
yarn upgrade
Corresponding commands for PNPM:
pnpm cache delete # command available from 9.x onwards only
pnpm start -- --reset-cache # double dash forwards extra arguments
pnpm clean
pnpm update
Why are there two double dashes?
npm startby itself runs whatever is defined under thestartscript in yourpackage.json(often something likereact-native startorexpo start).- To forward extra arguments to that underlying command, you add
--afternpm start. Everything after the--gets passed through.
Troubleshoot potential issues (FAQs)
How do you verify if you are using system bundles?
A couple of simple commands allow you to check whether your app is using system bundles.
Run:
vega exec vpt dump {path/to/vpkg} assets/raw/keplerscript-app-config.json > keplerscript-app-config.json
Open keplerscript-app-config.json and look for the "systemBundles": { section. If it is not present or is blank, the app is not using system bundles.
What likely happened here:
- Stale npm caches (did not run
npm updateor did not clear the cache properly)
npm cache clean --force # clears the global npm cache
npm start -- --reset-cache # clears metro cache
npm run clean # this assumes that you have a "clean" script in your package.json
npm update # pulls the latest version of your app's dependencies
I updated to the latest version, but my application is not using system bundles. What else can I check?
We previously (before 0.20.x) provided an opt-in/opt-out method for system bundles in two places:
-
In package.json’s “kepler” section, where we provided an optional flag called
useSystemJsBundles. Please remove references to that flag in your package.json. -
In the actual build command (which may be defined in your package.json as
react-native build-vegafor SDK 0.22+ orreact-native build-keplerfor earlier versions), you could set a flag for--use-system-js-bundlesas true or false. If you have defined this, please remove this flag.
If both flags are set, the command line flag takes precedence. If you have set the package.json version and are still running into the issue, double-check that your build command is not passing an incorrect value for --use-system-js-bundles.
How do I troubleshoot app crashes related to system bundles?
If a system bundle the app needs is not present in the OS, the app will crash. You’ll see a log like this:
28 D Volta:[KeplerScript-Native] System bundle not found at usr/lib/keplerscript-2/index.amzn__react-native-kepler-2.hermes.bundle
Process 'com.amazondeveloper.sample.main' (PID=107901) crashed with signal 6
App shows blank screen with “Requiring unknown module” error
This happens when the app bundle references a module that can’t be found in either the app bundle or the system bundles. The most common cause is a mismatch between the SDK version used to build the app and the OS version on the device or simulator.
Example error:
Uncaught Error: Requiring unknown module "2827612701754778". If you are sure the module exists,
try restarting Metro. You may also want to run `yarn` or `npm install`.
at unknownModuleError (index.bundle:365:17)
at loadModuleImplementation (index.bundle:285:31)
at guardedLoadModule (index.bundle:227:38)
at metroRequire (index.bundle:123:92)
To debug, search for the module ID (e.g. 2827612701754778) in the system libraries’ modules.txt to find which path is missing. That will tell you which library version caused the issue.
How to read the module ID format:
- IDs that are only digits (e.g.
3828144767075601) indicate the app was built with an SDK older than v0.18.1 - IDs that are hex strings (e.g.
2815fa36ee8494085256) use the newersha256-based mechanism introduced in v0.18.1
Solution: Make sure the SDK version used to build the app matches the OS version on the device. If you see numeric-only IDs, rebuild with a current SDK.
Failed to get system bundle path for: index.amzn__react-native-kepler-2.hermes.bundle
This issue happens if index.amzn__react-native-kepler-2.hermes.bundle is not present on the device. This file is expected to be located at /usr/local/share/bundles/index.amzn__react-native-kepler-2.hermes.bundle.
If you don’t see this file in that location, the OS version on the device is most likely not up to date.
package.json has legacy flag --split-bundle false
In the past you might have chosen to actively opt-out of split bundles. Your package.json might have included:
{
"scripts": {
"build:Debug": "react-native build-vega --build-type Debug --split-bundle false --build-number {number}"
}
}
Remove --split-bundle false to restore proper bundle splitting functionality.
Why doesn’t my app include system bundle entries when I build it?
This is likely because you’re building a debug version of your app. When an app is built in Debug mode, it doesn’t create split bundles.
To ensure your app includes system bundle entries, build and submit a Release version of your app. The Release build process creates split bundles, which include the necessary system bundle entries.
Related reading
- Recommended Semver Expressions for Amazon-Distributed Vega Libraries
- System Bundles: Smaller Apps and Faster Startups
Last updated: Mar 11, 2026