Get readable crash reports in the Crashlytics dashboard

By default, Firebase Crashlytics automatically instruments your Flutter project to upload the necessary symbol files that ensure crash reports are deobfuscated and human readable.

Unfortunately, there are cases that can result in the project not being fully configured. This guide outlines what the automation does and provides first steps to debug your project setup.

Apple platforms

Check your configuration for uploading dSYM files

Adding the Crashlytics Flutter plugin and running the flutterfire configure command will attempt to add a run script to your project’s Xcode workspace that finds and uploads the necessary dSYM symbol files to Crashlytics. Without these files, you’ll see a "Missing dSYM" alert in the Crashlytics dashboard and exceptions will be held by the backend until the missing files are uploaded.

If you have this issue, first make sure that you have the run script installed:

  1. Locate and open the Xcode workspace file in your project’s iOS directory (FLUTTER_PROJECT_NAME/ios/Runner.xcworkspace).

  2. Identify whether a run script titled [firebase_crashlytics] Crashlytics Upload Symbols has been added to the Runner target’s Build Phases.

    See the applicable section below for whether the run script does not exist or the run script exists.

Check your version configuration for Flutter and Crashlytics (if using the --split-debug-info flag)

If your Flutter project uses the --split-debug-info flag (and, optionally, also the --obfuscate flag), additional steps are required to show readable stack traces for your app.

Make sure that your project is using the recommended version configuration (Flutter 3.12.0+ and Crashlytics Flutter plugin 3.3.4+) so that your project can automatically generate and upload Flutter symbols (dSYM files) to Crashlytics.

Android

Check your dependency configuration

The flutterfire configure command attempts to add necessary dependencies to your project’s Gradle build files. Without these dependencies, crash reports in the Firebase console may end up obfuscated if obfuscation is turned on.

Make sure the following lines are present in the project-level build.gradle and in the app-level build.gradle:

  • In the project-level build file (android/build.gradle), check for the following line:

    dependencies {
// ... other dependencies

classpath 'com.google.gms:google-services:4.3.5'
classpath 'com.google.firebase:firebase-crashlytics-gradle:2.7.1'
}

  • In the app-level build file (android/app/build.gradle), check for the following line:

    // ... other imports

android {
// ... your android config
}

dependencies {
// ... your dependencies
}

// This section must appear at the bottom of the file
apply plugin: 'com.google.gms.google-services'
apply plugin: 'com.google.firebase.crashlytics'

Check that you're using the CLI to upload Flutter symbols (if using the --split-debug-info flag)

If your Flutter project uses the --split-debug-info flag (and, optionally, also the --obfuscate flag), additional steps are required to show readable stack traces for your app.

Use the Firebase CLI (v.11.9.0+) to upload Flutter debug symbols. You need to upload the debug symbols before reporting a crash from an obfuscated code build.

From the root directory of your Flutter project, run the following command:

firebase crashlytics:symbols:upload --app=FIREBASE_APP_ID PATH/TO/symbols

  • FIREBASE_APP_ID: Your Firebase Android App ID (not your package name)
    Example Firebase Android App ID: 1:567383003300:android:17104a2ced0c9b9b

  • PATH/TO/symbols: The same directory that you pass to the --split-debug-info flag when building the application

If problems persist, refer to the Android-specific guide for troubleshooting obfuscated reports.