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

iOS example:

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

Android example:

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

Release variant

If you have enabled Hermes on Android, see Uploading Hermes source maps.

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

iOS example (standard bundle):

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

Android example (standard bundle):

$ 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

iOS example:

$ curl 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`

Android example:

$ curl 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

iOS example:

$ curl 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`

Android example:

$ curl 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)
  • appBundleVersion (iOS only)

Alternatively, a codeBundleId should be supplied if using App Center CodePush.

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.

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

Deploying with App Center CodePush

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

Uploading Hermes source maps

If you are using Hermes on Android, when you have built the release variant of your app you will need to use the bugsnag-sourcemaps tool to upload source maps. For debug builds follow the standard instructions above.

$ npm install --global bugsnag-sourcemaps
$ 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, versionCode or codeBundleId.