Debugging Release Builds

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.

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.

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

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.

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

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

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

iOS

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.

+ 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.

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

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

# 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

• 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.