Debug App Crash Using Vega Studio

With Vega Studio, you can collect and analyze aggregated crash report (ACR) for your app running on your Fire TV Stick (device) or Vega Virtual Device (simulator). The process involves copying an ACR and symbolicating an ACR. You can collect and analyze reports for React Native for Vega apps and Turbo modules.

About ACR

An ACR is a file automatically generated when your app crashes on Fire TV devices or the Vega Virtual Device simulator. ACR contains raw crash data including memory addresses, stack traces, and system information. This data is stored in binary format on the device or simulator where the crash occurred.

To analyze crashes effectively, you need to:

1. Copy the ACR from your device or simulator.

2. Symbolicate the ACR to convert memory addresses into readable code references.

   ACRs is generated for both React Native for Vega apps and native Turbo modules.

Prerequisites

1. An ACR file that your app generated when it crashed.
2. Debug symbols or source maps (depending on code type).

3. Install libpython3.8 on your machine if developing on Ubuntu 22.04 or higher:

   Copy code Copied to clipboard.

   sudo add-apt-repository ppa:deadsnakes/ppa
   sudo apt update
   sudo apt install libpython3.8-dev
   

4. Binutils installed:

   On Mac, run:

   Copy code Copied to clipboard.

   brew install binutils
   

   Then, follow the on-screen instructions.

   On Ubuntu, run:

   Copy code Copied to clipboard.

   sudo apt install binutils 
   

Copy an ACR

1. Connect your target device to your computer.

   Vega displays connected devices in the sidebar. If you don't see your device, click the Refresh devices button. If you haven't connected a device, Vega selects the Vega Virtual Device by default.

2. Choose the desired target device from the sidebar.

3. Open the command palette in VS Code:

   • For Mac: shift + command ⌘ + p
   • For Linux: Ctrl + Shift + P

4. Enter Kepler Device Management: Copy ACR from device.

1. Enter the package id for your app or process id from the device or simulator.

   You can find the information in the [package] section on the manifest.toml.

   The package id is a unique identifier for your app while the process id identifies the specific process that runs your app on a device or simulator.

2. If the system finds multiple ACRs, you have two options:

   • Select All to download all available ACRs.
   • Select latest to only download the most recent ACR.

   Proceed with the download using the identified process or package ID, and your selected ACR option.

3. Save the ACR to your preferred folder.

Symbolicate an ACR

When your app crashes, it generates an ACR containing memory addresses and stack traces. These traces are difficult to read because they show only memory locations instead of actual code references.

Symbolication converts these cryptic memory addresses into readable information, showing you the exact files and line numbers where the crash occurred.

Example:

Before symbolication: 0x7ff8123456ab

After symbolication: my_function.ts:42

Launch symbolication

1. Open the command palette in VS Code:

   • For Mac: shift + command ⌘ + p
   • For Linux: Ctrl + Shift + P

2. Enter Kepler Device Management: Symbolicate ACR and press Enter.

3. Select your ACR file.

Select a symbolication option

Vega Studio prompts you to select a symbolication option. But before you select a symbolication option, check your package.json to validate your build configuration. If you use custom logic instead of react-native build-kepler to generate JS Hermes bytecode bundles or JS sourcemaps, follow these steps:

1. Proceed to Option 2: Manual symbolication.

2. Make sure your Metro-generated files follow these naming conventions:

   • JS plain-text bundle: index.bundle
   • JS source map: *.bundle.map

   

Option 1: Automatic symbolication

Vega Studio collects all required configuration parameters without your input. When finished, a symbolicated call stack appears in the terminal. For native code, a GDB debugging session opens automatically.

1. Wait while Vega Studio collects parameters.

2. If prompted for any missing parameters:

   • Read the request carefully.
   • Enter the requested information.
   • Click Continue.

   For example, during automatic native symbolication, if no device is connected, a prompt asks you to provide a debug rootfs.

3. View results:

   • Check symbolicated call stack in terminal.
   • For native code, a GDB debugging session opens automatically.

4. View the ACR:

   • For native code: The system generates an ACR report automatically when you close the GDB debugging session.

   • For JavaScript code: The system generates an ACR report automatically.

   • Vega Studio opens the ACR report automatically, showing processed information to help you diagnose the crash.

Option 2: Manual symbolication

In manual mode, Vega Studio analyzes your ACR to detect code types:

1. Wait for code type detection:

   • Native code only - Starts native workflow.
   • Mixed (native and JavaScript code) - Prompts you to select a decode type.

   

2. Select a decode type (if code type detection is mixed).

   Option 1: gdb (native mode) - Symbolicates native call stack.

   If this is your decode type, see Native mode for additional steps.

   Option 2: js (JavaScript mode) - Symbolicates JavaScript call stack.

   If this is your decode type, see JavaScript mode for additional steps.

Native mode

1. Select a symbol source:

   If your device is connected:

   • Device - Pulls symbols and libraries from the connected device.
   • Debug rootfs - Vega Studio prompts you to provide the debug rootfs.

   If your device isn’t connected, you must provide rootfs location when prompted.

   Note: A debug rootfs is a version of the Linux filesystem that contains debugging symbols and information for troubleshooting apps.

   

2. Add additional debug symbol folders:

   2.1. Select Yes to add a folder.

   2.2. Select folder location.

   2.3. Repeat or click No to finish.

   

3. View results:

   3.1. Look for symbolicated call stack in terminal.

   3.2. Use GDB debugging session.

4. View the ACR:

   When you close the GDB debugging session, the system generates an ACR and opens it in Vega Studio. The report contains processed crash information to help you diagnose the issue.

JavaScript mode

1. Provide a source map.

   1.1. Wait for source map prompt.

   1.2. At the prompt, click Browse.

   1.3. Navigate to project folder.

   1.4. Select index.bundle.map.

2. Add additional maps (optional).

   2.1. At the prompt, select Yes to add more maps.

   2.2. Select map file location.

   2.3. Repeat or select No to finish.

   

3. View symbolicated call stack in terminal.

4. View the ACR.

   The system generates an ACR report and opens it in Vega Studio automatically. The report contains processed crash information to help you diagnose the issue.

Common ACR issues

If you encounter issues when analyzing ACRs, see Fix Crash Analysis Issues.

Related topics

• Measure Performance with Chrome DevTools
• Monitor Network Traffic with Charles Proxy
• 💬 Community: Vega supported libraries and services

---

Last updated: Sep 30, 2025