Firebase Crashlytics in Flutter

What is Firebase Crashlytics in Flutter?

Firebase Crashlytics in Flutter is a production crash reporting tool that collects fatal crashes and non-fatal errors from real users. It helps identify stability issues that appear only in release builds and real-world conditions.

How does it work?

Crashlytics hooks into the Flutter error system and the platform runtime.

When an error occurs, it records:

• the exception and stack trace
• device and OS metadata
• app version and build number

Reports are sent to Firebase and grouped automatically by root cause.

Why does it matter in Flutter app development?

Many Flutter crashes:

• do not appear in Debug mode
• happen only on specific devices or OS versions
• are impossible to reproduce locally

Crashlytics provides visibility into real production failures, which is critical for maintaining app quality.

How to add Firebase Crashlytics to Flutter

After adding firebase_core and firebase_crashlytics, initialize error handling in main().

Recommended modern setup

FlutterError.onError =
    FirebaseCrashlytics.instance.recordFlutterFatalError;

PlatformDispatcher.instance.onError = (error, stack) {
  FirebaseCrashlytics.instance.recordError(
    error,
    stack,
    fatal: true,
  );
  return true;
};

This approach replaces older runZonedGuarded patterns and captures both:

• framework (UI) errors
• asynchronous errors outside the widget tree

When to use it?

Use Crashlytics when:

• The app is in beta or production.
• Stability is important.
• You need stack traces from release builds.
• Users rely on the app daily.

When not to use it?

Avoid Crashlytics when:

• Building throwaway prototypes.
• Handling highly sensitive data without consent.
• Crash reporting violates legal or privacy requirements.

Common mistakes to avoid

Missing async error handling

Using only FlutterError.onError misses many runtime crashes. Always register PlatformDispatcher.instance.onError.

Testing only Debug builds

Crashlytics works mainly in Release mode. Debug builds are not representative of production behavior.

iOS-specific pitfall: missing dSYM files

On iOS, Crashlytics requires dSYM files to decode crash reports. If dSYM files are not uploaded:

• Firebase shows "Missing dSYM".
• Stack traces are empty or unreadable.

You must configure a Run Script Phase in Xcode that uploads dSYM files automatically during build. Without this step, Crashlytics is effectively blind on iOS.

Obfuscation and readable crashes

If you build with obfuscation:

flutter build apk --obfuscate --split-debug-info=./symbols

Crash reports will be unreadable unless symbol files are uploaded. Always store and upload symbol mappings for each release.

Best practices

• Log non-fatal errors: Use recordError for handled exceptions. This exposes silent failures that hurt UX.
• Add custom context: Use setCustomKey and log to attach user actions or screen names. This often explains why a crash happened, not just where.
• Verify setup early: Trigger a test crash before releasing the app to confirm reports appear in Firebase.

Firebase Crashlytics Flutter Web

Crashlytics support for Flutter Web is limited:

• Stack traces are less precise.
• Some errors are handled as JavaScript exceptions.
• Reporting is less reliable than on mobile.

For web-heavy projects, consider combining Crashlytics with dedicated web error tracking tools.