Debug App Crash Using Vega Studio

When your React Native for Vega app or Turbo Module crashes on a Fire TV Stick or Vega Virtual Device, it generates an aggregated crash report (ACR) that you can use to identify exactly where and why the crash occurred.

This page shows you how to retrieve and symbolicate ACR files to identify exactly where and why your app crashed.

What is an ACR?

An ACR file contains three main sections:

1. Metadata - Searchable crash details including process name, crash time, and device information
2. Crash information - System state data such as memory usage and device logs at the time of crash
3. Dump section - Encoded crash state that requires symbolication to become readable

Symbolication converts the encoded dump section into readable code references:

Before symbolication:

0x7ff8123456ab libvega_core.so
0x7ff8987654cd libhermes.so
0x7ff8abcdef01 libvega_core.so

After symbolication:

libvega_core.so:render_frame:142
MyComponent.tsx:handlePress:87
libvega_core.so:event_dispatch:203

Each line shows: file:function:line_number

This transformation lets you identify the exact file, function, and line number where your app crashed.

Target audience

If you're building React Native for Vega apps or Turbo Modules and need to debug native crashes on Fire TV devices or Vega Virtual Devices, this page is for you. You should be familiar with:

• Building and deploying React Native for Vega apps or Turbo Modules
• Basic command-line tools
• Reading stack traces

Prerequisites

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

Quick reference

Use this quick reference to choose the right symbolication approach for your situation:

Your situation	Symbolication method	What it does
You built with react-native build-kepler	Automatic	Vega Studio finds all files automatically
You use custom build scripts	Manual	You specify symbol locations
You use a custom bundler configuration	Manual	You specify symbol locations
You generate bytecode bundles outside standard build	Manual	You specify symbol locations
You're unsure which method to use	Automatic	Try this first; switch to Manual if it fails

Retrieve and symbolicate an ACR

Vega Studio provides two ways to retrieve and symbolicate crash reports:

1. Quick method (recommended): Right-click workflow through the device sidebar.
2. Manual method: Command palette workflow with more control options.

Quick method: Right-click workflow

The simplest way to retrieve and symbolicate crash reports:

1. In the Vega Studio sidebar, locate your connected device.

2. Right-click on the device and select Show Crash Files.

   Vega Studio displays all available ACR files for that device.

3. Right-click on the crash file you want to analyze.

4. Select Symbolicate.

   Vega Studio automatically symbolicates the crash report and displays the results.

✓ Success: The symbolicated crash report opens with readable file paths and line numbers, showing exactly where your app crashed.

Manual method: Command palette workflow

Use this workflow when you need more control over the symbolication process or when working with saved ACR files.

Copy an ACR

Retrieve the ACR file from your device and save it locally:

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 don't have a connected device, Vega selects the Vega Virtual Device by default.

   For help connecting devices, see Run Your App on Vega Virtual Device or Fire TV Stick.

2. Open the command palette in VS Code:

   • For Mac: Shift+Command ⌘+P
   • For Linux: Ctrl+Shift+P

3. Enter Vega Device Management: Copy ACR from device.

4. Select your target device from the list if multiple devices are connected.

5. Enter the package id or process id:

   • Package ID (recommended): Use this to retrieve all ACRs for your app. Find it in the [package] section of your manifest.toml file (for example, com.example.myapp).
   • Process ID: Use this to retrieve ACRs for a specific app instance. Get it from the device's running processes (for example, 12345).

   When in doubt, use the package ID as it captures all crashes for your app regardless of which process instance crashed.

6. If the system finds multiple ACRs, select which to download:

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

7. Save the ACR to your preferred folder.

✓ Success: You should now have an ACR file saved locally. The file name typically includes a timestamp and process information.

Symbolicate an ACR

The ACR file you just copied contains raw crash data with memory addresses and stack traces that are difficult to read because they show only memory locations instead of actual code references. Thus, you must symbolicate an ACR.

Launch symbolication

1. Open the command palette in VS Code:

   • For Mac: Shift+Command ⌘+P
   • For Linux: Ctrl+Shift+P

2. Enter Vega 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:

• Automatic: Vega Studio automatically locates all required files and symbols.
• Manual: You specify symbol locations manually.

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 GNU Debugger (GDB) session opens automatically for interactive debugging.

1. Wait for Vega Studio to collect 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 connects, a prompt asks you to provide a debug rootfs.

3. View results:

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

4. View the ACR summary:

   Vega Studio generates and opens an ACR summary automatically:

   • For native code: After you close the GDB debugging session
   • For JavaScript code: Immediately after symbolication completes

✓ Success: The terminal displays a symbolicated call stack with readable file paths and line numbers. For native crashes, the GDB session allows you to inspect the crash state.

Manual symbolication

Before you begin manual symbolication, 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, make sure your Metro-generated files follow these naming conventions:

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

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

• Native code only: Starts native symbolication workflow automatically.

• Mixed (native and JavaScript code): Prompts you to select a symbolication type.

  

Symbolicate native code only

If Vega Studio detects native code only, it prompts you to:

1. Select a symbol source:

   

   If your device connects:

   • Device - Pulls symbols and libraries from the connected device
   • Debug rootfs - Vega Studio prompts you to provide the debug rootfs location (a Linux filesystem version with debugging symbols for troubleshooting apps)

   If your device doesn't connect:

   You must provide a debug rootfs location when prompted.

   

2. Add additional debug symbol folders (optional):

   a. Select Yes to add a folder.

   b. Select the folder location.

   c. Repeat or click No to finish.

3. View results:

   a. Review the symbolicated call stack in the terminal. This shows the exact code locations where the crash occurred.

   b. Use the GDB debugging session to:

   • Inspect variables and memory at the crash point
   • Navigate through the call stack
   • Examine the program state when it crashed

4. View the ACR summary:

   When you close the GDB debugging session, Vega Studio generates and opens an ACR summary with processed crash information.

✓ Success: The terminal shows symbolicated native code with readable function names and line numbers. The GDB session allows interactive debugging.

Symbolicate JavaScript code only

If Vega Studio detects JavaScript code only:

1. Wait for source map prompt.
2. At the prompt, click Browse.
3. Navigate to the project folder.
4. Select <hash>.bundle.map.

5. Add additional maps (optional):

   • At the prompt, select Yes to add more maps.
   • Select the map file location.
   • Repeat or select No to finish.

6. Review the symbolicated call stack in the terminal. This shows the exact JavaScript files and line numbers where the crash occurred.

7. View the ACR summary:

   Vega Studio generates and opens an ACR summary automatically with processed crash information to help you identify the root cause.

✓ Success: The terminal displays JavaScript stack traces with readable file paths (for example, MyComponent.tsx:87) instead of memory addresses.

Symbolicate mixed code (native and JavaScript)

If Vega Studio detects mixed code, choose which code type to symbolicate:

• To symbolicate native code (using gdb), follow the steps in Symbolicate native code only.
• To symbolicate JavaScript (using js), follow the steps in Symbolicate JavaScript code only.

After symbolication completes, see Read and Use the ACR Summary Report to understand the generated report and its diagnostic information.

Next steps

After you've symbolicated your ACR:

1. Analyze the crash: Review the ACR Summary Report to understand what caused the crash.
2. Identify the root cause: Use Detect Where the App Crash Originates to determine if it's a JavaScript error, native crash, or system issue.
3. Fix the issue: Navigate to the identified file and line number in your code to implement a fix.
4. Test your fix: Run your app on the same device type where the crash occurred to verify the fix.
5. Monitor for recurrence: Check device logs after deployment to ensure the crash doesn't reappear.

Troubleshooting

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

Related topics

• Detect Where the App Crash Originates
• Manage Files, Crash Reports, and Logs
• 💬 Community: Vega supported libraries and services

---

Last updated: Feb 11, 2026