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 1897918998 E AndroidRuntime: FATAL EXCEPTION: mqt_native_modules
07-15 10:58:25.820 1897918998 E AndroidRuntime: Process: com.awesomeproject, PID: 18979 07-15 10:58:25.820 1897918998 E AndroidRuntime: com.facebook.react.common.JavascriptException: Failed, js engine: hermes, stack:
07-15 10:58:25.820 1897918998 E AndroidRuntime: p@1:132161
07-15 10:58:25.820 1897918998 E AndroidRuntime: p@1:132084
07-15 10:58:25.820 1897918998 E AndroidRuntime: f@1:131854
07-15 10:58:25.820 1897918998 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
- iOS
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
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_FILEentry 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-symbolicateexits immediately with success, make sure the input comes from a pipe or redirection and not from a terminal.