ContextQMD
Back to React Native

Debugging Release Builds

website/versioned_docs/version-0.83/debugging-release-builds.md

latest3.9 KB
Original Source

import Tabs from '@theme/Tabs'; import TabItem from '@theme/TabItem'; import constants from '@site/core/TabsConstants';

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.

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.

<Tabs groupId="platform" queryString defaultValue={constants.defaultPlatform} values={constants.platforms} className="pill-tabs"> <TabItem value="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.

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
</TabItem> <TabItem value="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.
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
</TabItem> </Tabs>

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

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