# Troubleshooting Guide for System Bundles

**URL:** <https://community.amazondeveloper.com/t/troubleshooting-guide-for-system-bundles/20164>\
**Category:** Knowledge Base\
**Created:** [February 23, 2026, 6:00am UTC](https://community.amazondeveloper.com/t/troubleshooting-guide-for-system-bundles/20164 "2026-02-23T06:00:00Z")\
**Posts on this page:** 1\
**Page:** 1

<div class="post-metadata">

**Author:** ![cebratec](https://dhm3gbtzu79o6.cloudfront.net/user_avatar/community.amazondeveloper.com/cebratec/32/2276_2.png) [@cebratec](https://community.amazondeveloper.com/u/cebratec)\
**Post date:** [February 23, 2026, 6:00am UTC](https://community.amazondeveloper.com/t/troubleshooting-guide-for-system-bundles/20164/1 "2026-02-23T06:00:00Z")

</div>

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

```bash
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:

```bash
yarn cache clean --all
yarn start -- --reset-cache # double dash forwards extra arguments
yarn clean
yarn upgrade

```

Corresponding commands for PNPM:

```bash
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?

1. `npm start` by itself runs whatever is defined under the `start` script in your `package.json` (often something like `react-native start` or `expo start`).
2. To forward extra arguments to that underlying command, you add `--` after `npm 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:

```bash
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 update` or did not clear the cache properly)

```bash
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:

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 command (which may be defined in your package.json as `react-native build-vega` for SDK 0.22+ or `react-native build-kepler` for earlier versions), 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 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:

```bash
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:

```auto
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 newer `sha256`-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:

```json
{
    "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](https://community.amazondeveloper.com/t/package-json-semver-guidance-for-amazon-distributed-libraries-on-vega/11643)
- [System Bundles: Smaller Apps and Faster Startups](https://community.amazondeveloper.com/t/a-developers-guide-understanding-system-bundles-in-apps-for-amazon-fire-tv/20167)

_Last updated: Mar 11, 2026_