# Source: https://reactnative.dev/docs/debugging-release-builds.md

# Debugging Release Builds

## Symbolicating a stack trace[​](#symbolicating-a-stack-trace "Direct link to Symbolicating a stack trace")

If a React Native app throws an unhandled exception in a release build, the output may be obfuscated and hard to read.

shell

```
07-15 10:58:25.820 18979 18998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 18979 18998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 18979 18998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 18979 18998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 18979 18998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 18979 18998 E AndroidRuntime: anonymous@1:131119
```

In the above stack trace, entries like `p@1:132161` are minified function names and bytecode offsets. To debug these calls, we want to translate these into file, line, and function name, e.g. `AwesomeProject/App.js:54:initializeMap`. This is known as **symbolication.**

You can symbolicate minified function names and bytecode like the above by passing the stack trace and a generated source map to [`metro-symbolicate`](https://www.npmjs.com/package/metro-symbolicate).

### Enabling source maps[​](#enabling-source-maps "Direct link to Enabling source maps")

Source maps are required to symbolicate stack traces. Make sure that source maps are enabled within the build config for the target platform.

* Android
* iOS

info

On Android, source maps are **enabled** by default.

To enable source map generation, ensure the following `hermesFlags` are present in `android/app/build.gradle`.

groovy

```
react {
    hermesFlags = ["-O", "-output-source-map"]
}
```

If done correctly you should see the output location of the source map during Metro build output.

text

```
Writing bundle output to:, android/app/build/generated/assets/react/release/index.android.bundle
Writing sourcemap output to:, android/app/build/intermediates/sourcemaps/react/release/index.android.bundle.packager.map
```

info

On iOS, source maps are **disabled** by default. Use the following instructions to enable them.

To enable source map generation:

* Open Xcode and edit the build phase "Bundle React Native code and images".
* Above the other exports, add a `SOURCEMAP_FILE` entry with the desired output path.

diff

```
+ export SOURCEMAP_FILE="$(pwd)/../main.jsbundle.map"
  WITH_ENVIRONMENT="../node_modules/react-native/scripts/xcode/with-environment.sh"
```

If done correctly you should see the output location of the source map during Metro build output.

text

```
Writing bundle output to:, Build/Intermediates.noindex/ArchiveIntermediates/application/BuildProductsPath/Release-iphoneos/main.jsbundle
Writing sourcemap output to:, Build/Intermediates.noindex/ArchiveIntermediates/application/BuildProductsPath/Release-iphoneos/main.jsbundle.map
```

### Using `metro-symbolicate`[​](#using-metro-symbolicate "Direct link to using-metro-symbolicate")

With source maps being generated, we can now translate our stack traces.

shell

```
# Print usage instructions
npx metro-symbolicate

# From a file containing the stack trace
npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map < stacktrace.txt

# From adb logcat (Android)
adb logcat -d | npx metro-symbolicate android/app/build/generated/sourcemaps/react/release/index.android.bundle.map
```

### Notes on source maps[​](#notes-on-source-maps "Direct link to Notes on source maps")

* Multiple source maps may be generated by the build process. Make sure to use the one in the location shown in the examples.
* Make sure that the source map you use corresponds to the exact commit of the crashing app. Small changes in source code can cause large differences in offsets.
* If `metro-symbolicate` exits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.