Showing full stacktraces

BugSnag supports unminifying and demangling stacktraces using ProGuard files, LLVM debug symbol maps (dSYMs), and source maps to show a full stacktrace with methods, file paths, and line numbers for JavaScript and native errors.

Uploading mapping files for Android

If you have enabled ProGuard or use the NDK, you will need to send mapping files to our Upload API in order to deobfuscate Android stack traces. Adding the BugSnag Android Gradle Plugin to your project will perform this task automatically.

Uploading debug symbol maps (dSYMs) for iOS

You will need to send dSYM files to our Upload API in order to symbolicate native iOS stack traces. Our iOS symbolication guide provides details on how to automate this process.

Uploading source maps

Upload source maps to BugSnag to unminify JavaScript stack traces. Separate source maps must be generated and uploaded for Android and iOS.

In addition to standard bundles, the Random Access Modules (RAM) bundle format is also supported.

Delta bundles used in dev mode are not supported. They can be disabled via the in-app developer menu.

Generating source maps

#Debug variant

The source maps used for the debug variant can be downloaded from the Metro bundler server.

curl "http://localhost:8081/index.bundle?platform=ios&dev=true&minify=false" > ios-debug.bundle
curl "http://localhost:8081/index.map?platform=ios&dev=true&minify=false" > ios-debug.bundle.map

curl "http://localhost:8081/index.bundle?platform=android&dev=true&minify=false" > android-debug.bundle
curl "http://localhost:8081/index.map?platform=android&dev=true&minify=false" > android-debug.bundle.map

#Release variant

The source maps used for the release variant can be generated via the react-native bundle (or react-native ram-bundle) command.

react-native bundle \
    --platform ios \
    --dev false \
    --entry-file index.js \
    --bundle-output ios-release.bundle \
    --sourcemap-output ios-release.bundle.map

react-native bundle \
    --platform android \
    --dev false \
    --entry-file index.js \
    --bundle-output android-release.bundle \
    --sourcemap-output android-release.bundle.map

Uploading source maps to BugSnag

The generated source map and bundle file should be uploaded using the React Native source map upload API.

#Debug variant

curl --http1.1 https://upload.bugsnag.com/react-native-source-map \
   -F apiKey=YOUR_API_KEY_HERE \
   -F appVersion=1.2.3 \
   -F dev=true \
   -F platform=ios \
   -F sourceMap=@ios-debug.bundle.map \
   -F bundle=@ios-debug.bundle \
   -F projectRoot=`pwd`

curl --http1.1 https://upload.bugsnag.com/react-native-source-map \
   -F apiKey=YOUR_API_KEY_HERE \
   -F appVersion=1.2.3 \
   -F dev=true \
   -F platform=android \
   -F sourceMap=@android-debug.bundle.map \
   -F bundle=@android-debug.bundle \
   -F projectRoot=`pwd`

#Release variant

curl --http1.1 https://upload.bugsnag.com/react-native-source-map \
   -F apiKey=YOUR_API_KEY_HERE \
   -F appVersion=1.2.3 \
   -F dev=false \
   -F platform=ios \
   -F sourceMap=@ios-release.bundle.map \
   -F bundle=@ios-release.bundle \
   -F projectRoot=`pwd`

curl --http1.1 https://upload.bugsnag.com/react-native-source-map \
   -F apiKey=YOUR_API_KEY_HERE \
   -F appVersion=1.2.3 \
   -F dev=false \
   -F platform=android \
   -F sourceMap=@android-release.bundle.map \
   -F bundle=@android-release.bundle \
   -F projectRoot=`pwd`

Selecting an app version

When uploading source maps to BugSnag at least one of the following versions must be supplied: appVersion, appVersionCode (Android only) OR appBundleVersion (iOS only).

Alternatively, a codeBundleId should be supplied if using App Center CodePush. You should then follow the Deploying with App Center CodePush instructions.

BugSnag matches source maps to events using the following order of precedence:

1. codeBundleId
2. appVersion AND appVersionCode / appBundleVersion
3. appVersionCode
4. appVersion

Please note that any supplied values should match the equivalent version fields shown in the “App” tab of the error you are attempting to symbolicate.

#Using package.json versioning

If you update your app’s version in your package.json, then you should set appVersion to this value when initializing BugSnag:

import { Client, Configuration } from 'bugsnag-react-native';

const config = new Configuration('your-API-key');
config.appVersion = require('./package.json').version;
const bugsnag = new Client(config);

Then when you upload your source maps set the appVersion parameter to the same value.

#Using native versioning

If you don’t set the version in your package.json you should provide the following when uploading source maps:

• iOS: set the appBundleVersion parameter to the value of the Build Number (called versionCode in BugSnag)

• Android: set the appVersionCode parameter to the value of the versionCode

These values are included by default in error reports and are shown on the “App” tab.

Deploying with App Center CodePush

If you use App Center CodePush, lock the library to the latest patch version:

"dependencies": {
    "bugsnag-react-native": "~2.10.1"
}

This prevents CodePush releases from causing undefined behaviour in the Native Components of bugsnag-react-native.

When you push JavaScript updates to your React Native app without changing the binary, a single app version applies to multiple JavaScript bundles.

In order to get unminified JavaScript stack traces, you will need to use a code bundle identifier (codeBundleId) instead of an appVersion, appVersionCode, or appBundleVersion when uploading source maps to BugSnag.

During each deploy, complete the following steps:

1. Define and set a code bundle identifier in your BugSnag configuration before each release. This identifier can be any string as long as it matches what is sent to the source map upload API in step 3.

   const config = new Configuration('YOUR_API_KEY_HERE');
   config.codeBundleId = '1.0.0-b12'
   const bugsnag = new Client(config);
   

2. Release an update for your app using App Center CodePush, specifying the --output-dir in order to capture the source map and asset bundle files for upload in step 3.

   appcenter codepush release-react \
       --app <ownerName>/<appName> \
       --output-dir build
   

3. Upload the source map, specifying the code bundle identifier in place of the app version/app version code.

   on iOS:

   curl --http1.1 https://upload.bugsnag.com/react-native-source-map \
       -F apiKey=YOUR_API_KEY_HERE \
       -F codeBundleId=1.0.0-b12 \
       -F dev=false \
       -F platform=ios \
       -F sourceMap=@ios-release.bundle.map \
       -F bundle=@ios-release.bundle \
       -F projectRoot=`pwd`
   

   on Android:

   curl --http1.1 https://upload.bugsnag.com/react-native-source-map \
       -F apiKey=YOUR_API_KEY_HERE \
       -F codeBundleId=1.0.0-b12 \
       -F dev=false \
       -F platform=android \
       -F sourceMap=@android-release.bundle.map \
       -F bundle=@android-release.bundle \
       -F projectRoot=`pwd`
   

4. Repeat steps 2 and 3 for iOS or Android if you support both platforms.

Generating and Uploading Hermes source maps

If you are using Hermes on Android, you can use the standard instructions above for debug builds. For a release build, you will need to build a release variant prior to running CodePush on your application in order to produce the appropriate minifiedFile and source-map, either by running the release variant using react-native:

react-native run-android --variant=release

or, building the release variant directly with gradlew:

./android/gradlew assembleRelease

Then, use the bugsnag-sourcemaps tool to upload the generated source maps. The bundle and source map will be generated in the directories shown in the commands below.

npm install --global bugsnag-sourcemaps

#Without App Center CodePush

bugsnag-sourcemaps upload \
  --api-key=YOUR_API_KEY_HERE \
  --app-version=1.2.3 \
  --minifiedFile=android/app/build/generated/assets/react/release/index.android.bundle \
  --source-map=android/app/build/generated/sourcemaps/react/release/index.android.bundle.map \
  --minified-url=index.android.bundle \
  --upload-sources

The --app-version can be set to either your app’s appVersion or versionCode.

#With App Center CodePush

If you are using App Center CodePush you will need to use the --code-bundle-id and --add-wildcard-prefix options instead of --app-version.

bugsnag-sourcemaps upload \
  --api-key=YOUR_API_KEY_HERE \
  --code-bundle-id=1.0.0-b12 \
  --minifiedFile=android/app/build/generated/assets/react/release/index.android.bundle \
  --source-map=android/app/build/generated/sourcemaps/react/release/index.android.bundle.map \
  --minified-url=index.android.bundle \
  --upload-sources \
  --add-wildcard-prefix