We previously announced the introduction of system bundles (also known as JS Bundles in System) and rolled this feature out gradually along with 0.18-0.20 releases. In case there are any outstanding troubleshooting questions, we’ve collected previous posts here.
Previous posts in chronological order:
- App submission common errors plus new validation tools now available
- Package.json semver guidance for Amazon distributed libraries on Vega
- Understanding System Bundles in Apps for Amazon Fire TV
As a refresher, we will talk about how to build and debug with bundle splitting, how to verify it and how the terms bundle splitting and system bundles relate (spoiler, they are the same).
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 to verify if you are using system bundles?
Couple of simple commands allow you to see for yourself if you are using system bundles or not.
Run:
kepler exec vpt dump {path/to/vpkg} assets/raw/keplerscript-app-config.json > keplerscript-app-config.json
Proceed to open keplerscript-app-config.json and look for "systemBundles": { section. If it is not present or blank, it means that the app is not using any system bundles.
What likely happened here:
- stale npm caches (did not run
npm updateor cleared 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 0.20.x, 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: 1) In package.json’s “kepler” section, where we provided an optional flag called useSystemJsBundles . Please remove references to that flag in your package.json. 2) In the actual build-kepler command (which may also be defined in your package.json , you could set a flag for --use-system-js-bundles as true or false. If you have defined this, please remove this flag. If both flags are set, the command line “wins”, so if you have set the package.json version and are still running into the issue, double check that your command line is not passing in an incorrect version of --use-system-js-bundles .
How do I troubleshoot App Crashes related to system bundle?
If a system bundle the app needs is not present in the OS, then this log will occur. The app will crash (your IDE will abort the app) if a required system bundle is not present.
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 and log shows error “Requiring unknown module”, what should I try?
An app bundle requires a definition but it could not be found either in the app bundle or in JS bundles in the System. This issue could happen if the bundle loaded from OS is not compatible with the version the app was built against. Typically this issue is seen when code in the SDK is different from the one on the device or simulator.
To debug this issue, search for 2827612701754778 this is one of the modules.txt of system libraries to find which path is missing. Based on that path we would know the version of the library that caused this issue.
To fix we have to make sure that SDK and OS are same.
bar-2::module1::printModule1
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)
at anonymous (index.bundle:1469:18)
at loadModuleImplementation (index.bundle:328:14)
at guardedLoadModule (index.bundle:219:47)
at metroRequire (index.bundle:123:92)
at global (index.bundle:1523:4)
Similar issues to the one above describe are:
App shows blank screen and log shows error :Volta:Error: Requiring unknown module "1949495132302115" → The app requires the definition of a module, but the same module definition is not present in the OS being used to test.
App shows blank screen and log shows Requiring unknown module “3828144767075601”. → Similar to above 2 issues, this issue happens due to mismatch of OS and SDK used to build the app. As of SDK v0.18.1, the external build bundle split tool is updated to use a different ID mechanism. This ID mechanism uses sha256 bits truncated to 20 chars. So new IDs will look like 2815fa36ee8494085256 combination of [0-9a-f]+. If the error shows only numbers e.g. 3828144767075601 then the root cause for the issue : app is using older version of SDK to build.
Solution: Rebuild the app with new 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 in 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 then most likely the OS version used to test is not up to date.
package.json has legacy flag --split-bundle false
In the past you might’ve chosen to actively opt-out of split bundles. Your package.json might had included:
{
"scripts": {
"build:Debug": "react-native build-kepler --build-type Debug --build-number {number} --split-bundle false"
}
}
Remove --split-bundle false as it will block proper 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. Here’s what you need to know. When an app is built in Debug mode, it doesn’t create split bundles.
To ensure your app includes system bundle entries, make sure you’re building and submitting a release version of your app, not a debug version. The release build process creates split bundles, which include the necessary system bundle entries.