---
title: Crashlytics
description: >-
  Crashlytics: getCrashlytics, log, setUserId/setAttribute(s), recordError,
  crash, collection toggles, unsent-report helpers, SDK_VERSION, and
  firebase.json flags for auto-collection, debug mode and JS exception handling.
next: /crashlytics/android-setup
previous: /app/utils
---
> ## Documentation Index
> Fetch the complete documentation index at: https://rnfirebase.io/llms.txt
> Use this file to discover all available pages before exploring further.

## Prerequisites

- `@react-native-firebase/app` installed and native config completed per [Getting Started](/) (Android `google-services.json`, iOS `GoogleService-Info.plist`, Expo config plugin, or React Native CLI setup). From v26, New Architecture is required for packages with a native bridge.
- Install Crashlytics: `npm install --save @react-native-firebase/crashlytics` or `yarn add @react-native-firebase/crashlytics`, then rebuild native apps (`cd ios && pod install` on iOS).
- Complete [Android Additional Setup](/crashlytics/android-setup) for React Native CLI Android builds (for Expo, the config plugin covers only steps 2 and 3 of Android Setup).
- Enable Crashlytics for your Firebase project in the [Firebase Console](https://console.firebase.google.com/). Crashlytics supports only the default Firebase app. There is no firebase-js-sdk web Crashlytics module (`firebase/crashlytics` does not exist).

Example Expo Router screen: https://github.com/invertase/react-native-firebase/blob/main/test-expo/app/crashlytics.tsx

# Installation

This module requires that the `@react-native-firebase/app` module is already setup and installed. To install the "app" module, view the
[Getting Started](/) documentation.

```bash
# Install & setup the app module
yarn add @react-native-firebase/app

# Install the Crashlytics module
yarn add @react-native-firebase/crashlytics

# If you're developing your app using iOS, run this command
cd ios/ && pod install
```

Once installed, you must complete the following additional setup steps for Android:

- [Android Additional Setup](/crashlytics/android-setup).

> If you're using Expo, make sure to add the `@react-native-firebase/crashlytics` config plugin to your `app.json` or `app.config.js`. On Android it covers only steps 2 and 3 of [Android Setup](/crashlytics/android-setup) (adding the Crashlytics Gradle plugin dependency and applying the plugin); the Google repository (step 1) and the optional NDK block (step 4) are not added by the plugin, so follow steps 1 and 4 on the [Android Setup](/crashlytics/android-setup) page. Steps 1 and 4 need a native `android/` folder, which `npx expo prebuild` generates in an Expo project. Because that folder is regenerated by `npx expo prebuild --clean` and by EAS Build, edits made directly in it may not persist, so a workflow that regenerates it needs those changes made another way (for example a custom config plugin). For instructions on adding the plugin, view the [Expo](/#installation-for-expo-projects) installation section.

> You may like reading a short article we wrote that explains how to configure and _most importantly_ verify your crashlytics installation so you are sure it is working. https://invertase.io/blog/react-native-firebase-crashlytics-configuration

# Platform support and New Architecture

{/* prettier-ignore */}
| | |
| --- | --- |
| **Platforms** | Android, iOS (native Firebase SDK) |
| **New Architecture** | **Required** from v26. See [Migrating to v26](/migrating-to-v26#new-architecture-requirement). |

**Platform notes:** Crashlytics is native-only. The firebase-js-sdk does not ship a modular public API for this product, so there is no web parity surface under `firebase/crashlytics`. Crashlytics supports only the default Firebase app. React Native Firebase exports `SDK_VERSION`, `getCrashlytics`, `log`, `setUserId`, `setAttribute`, `setAttributes`, `recordError`, `crash`, `setCrashlyticsCollectionEnabled`, `checkForUnsentReports`, `sendUnsentReports`, `deleteUnsentReports`, `didCrashOnPreviousExecution` and the `Crashlytics` instance type. The package type declarations also contain a legacy `Statics` interface, but the package entry point does not export it. Each export is explained in the section that uses it.

# What does it do

Crashlytics helps you to collect analytics and details about crashes and errors that occur in your app. It does this through three aspects:

- **Logs**: Log events in your app to be sent with the crash report for context if your app crashes.
- **Crash reports**: Every crash is automatically turned into a crash report and sent.
- **Stack traces**: Even when an error is caught and your app recovers, the JavaScript stack trace can still be sent.

<YouTube id="k_mdNRZzd30" />

To learn more, view the [Firebase Crashlytics documentation](https://firebase.google.com/docs/crashlytics?utm_source=invertase&utm_medium=react-native-firebase&utm_campaign=crashlytics).

# Usage

Use the `log` method throughout your app to accumulate extra context for possible crashes that can happen. For additional context, Crashlytics also offers [various methods](/crashlytics/usage#crash-attributes) to set attributes for the crash report. You can also test Crashlytics by forcing a crash through the `crash` method.

Crashlytics also supports sending JavaScript stack traces to the Firebase console. This can be used in any situation where an error occurs but is caught by your own code to recover gracefully. To send a stack trace, pass a JavaScript Error to the `recordError` method.

> In debug builds on Android and iOS, Crashlytics collection is disabled unless `crashlytics_debug_enabled` is `true` in `firebase.json`. While collection is disabled, the native module ignores `setUserId`, `setAttribute`, `setAttributes` and `recordError` calls, and `crash` does nothing. To enable collection in debug builds, view the [enable debug crash logs](/crashlytics/usage#enable-debug-crash-logs) documentation.

## Get a Crashlytics instance

`getCrashlytics` returns the `Crashlytics` module instance for the default Firebase app only. Crashlytics does not support secondary Firebase apps. Passing `getApp()` still resolves that same default-app instance. The firebase-js-sdk does not ship this helper.

```js
import { getApp } from '@react-native-firebase/app';
import { getCrashlytics } from '@react-native-firebase/crashlytics';

function readCrashlyticsInstance() {
  const crashlytics = getCrashlytics();
  const sameDefaultApp = getCrashlytics(getApp());
  console.log('Default app name:', crashlytics.app.name);
  console.log('Collection enabled:', crashlytics.isCrashlyticsCollectionEnabled);
  console.log('Same instance for default app:', sameDefaultApp === crashlytics);
}
```

`Crashlytics` is the TypeScript type of that instance (methods such as `log` and `recordError` take a `Crashlytics` as their first argument).

## Crash Attributes

There are various methods to set attributes for the crash report, in order to provide analytics for crashes and help you review them. `setUserId` identifies the user, `setAttribute` and `setAttributes` set custom keys, and `log` adds a message to the report log.

- `setUserId`, `setAttribute` and `setAttributes` return a `Promise`. `log` is synchronous and returns `void`.
- Attribute values must be strings. `setAttribute` throws if the name or value is not a string, and `setUserId` throws if the user id is not a string. `setAttributes` throws if its argument is not an object. Convert numbers and true or false values with `String()` before passing them.
- While Crashlytics collection is disabled, the native module ignores `setUserId`, `setAttribute` and `setAttributes`. It also ignores `log` on Android.

```jsx
import React, { useEffect } from 'react';
import { View, Button } from 'react-native';
import {
  getCrashlytics,
  log,
  setUserId,
  setAttribute,
  setAttributes,
  crash,
} from '@react-native-firebase/crashlytics';

async function onSignIn(user) {
  const crashlytics = getCrashlytics();
  log(crashlytics, 'User signed in.');
  await Promise.all([
    setUserId(crashlytics, user.uid),
    setAttribute(crashlytics, 'credits', String(user.credits)),
    setAttributes(crashlytics, {
      role: 'admin',
      followers: '13',
      email: user.email,
      username: user.username,
    }),
  ]);
}

export default function App() {
  useEffect(() => {
    log(getCrashlytics(), 'App mounted.');
  }, []);

  return (
    <View>
      <Button
        title="Sign In"
        onPress={() =>
          onSignIn({
            uid: 'Aa0Bb1Cc2Dd3Ee4Ff5Gg6Hh7Ii8Jj9',
            username: 'Joaquin Phoenix',
            email: 'phoenix@example.com',
            credits: 42,
          })
        }
      />
      {/* WARNING: crash() forces a native crash when collection is enabled and does nothing when it is disabled. Debug builds do not send reports unless crashlytics_debug_enabled is set, and an attached debugger stops the crash first, so test with a release build. */}
      <Button title="Test Crash" onPress={() => crash(getCrashlytics())} />
    </View>
  );
}
```

## Error Reports

Even if you catch unexpected errors, in order for your app to recover and behave smoothly you can still report them through
Crashlytics using the `recordError` method. This will also provide you with the associated stack trace.

- `recordError(crashlytics, error, jsErrorName?)` returns `void`. The optional `jsErrorName` is added to the report as an extra first stack frame (with the name as the file), which can help you tell reports apart in the console.
- The `error` argument must be an `Error` instance. For anything else, `recordError` logs a console warning and ignores the call.
- While Crashlytics collection is disabled, the native module ignores the call.
- Recorded errors are non-fatal events. Crashlytics stores them on the device and sends them with the next fatal event report or when the app restarts.

```jsx
import React, { useState, useEffect } from 'react';
import { View, Button, Text } from 'react-native';
import { getCrashlytics, log, recordError } from '@react-native-firebase/crashlytics';

export default function App() {
  const [status, setStatus] = useState('idle');

  useEffect(() => {
    log(getCrashlytics(), 'App mounted.');
  }, []);

  async function loadUsers() {
    const crashlytics = getCrashlytics();
    log(crashlytics, 'Updating user count.');
    try {
      const response = await fetch('https://example.com/users.json');
      if (!response.ok) {
        throw new Error(`Request failed with status ${response.status}`);
      }
      const users = await response.json();
      setStatus(`Loaded ${users.length} users.`);
    } catch (error) {
      if (error instanceof Error) {
        recordError(crashlytics, error, 'LoadUsersError');
        setStatus(error.message);
      }
      console.log(error);
    }
  }

  return (
    <View>
      <Button title="Load Users" onPress={loadUsers} />
      <Text>{status}</Text>
    </View>
  );
}
```

## Opt-out

As Crashlytics will be sending certain information regarding the user, users may want to opt-out of the crash reporting.
This can be done throughout the app with a simple method call to `setCrashlyticsCollectionEnabled`.

- `setCrashlyticsCollectionEnabled(crashlytics, enabled)` throws if `enabled` is not a boolean and returns a `Promise`.
- The module stores the value on the device, so it is used on later launches and takes priority over the `crashlytics_auto_collection_enabled` value in `firebase.json`.
- `crashlytics.isCrashlyticsCollectionEnabled` is a read-only property that reflects the last value you set, or the startup value if you have not set one.
- In a debug build without `crashlytics_debug_enabled`, native collection stays disabled even after you call `setCrashlyticsCollectionEnabled(crashlytics, true)`, although the property then reads `true`.

```jsx
import React, { useState } from 'react';
import { View, Button, Text } from 'react-native';
import {
  getCrashlytics,
  setCrashlyticsCollectionEnabled,
  crash,
} from '@react-native-firebase/crashlytics';

export default function App() {
  const [enabled, setEnabled] = useState(getCrashlytics().isCrashlyticsCollectionEnabled);

  async function toggleCrashlytics() {
    const crashlytics = getCrashlytics();
    await setCrashlyticsCollectionEnabled(crashlytics, !enabled);
    setEnabled(crashlytics.isCrashlyticsCollectionEnabled);
  }

  return (
    <View>
      <Button title="Toggle Crashlytics" onPress={toggleCrashlytics} />
      {/* WARNING: crash() forces a native crash when collection is enabled and does nothing when it is disabled. Debug builds do not send reports unless crashlytics_debug_enabled is set, and an attached debugger stops the crash first, so test with a release build. */}
      <Button title="Crash" onPress={() => crash(getCrashlytics())} />
      <Text>Crashlytics collection is {enabled ? 'enabled' : 'disabled'}</Text>
    </View>
  );
}
```

## Unsent reports and previous crashes

When automatic collection is disabled (via `firebase.json` and/or `setCrashlyticsCollectionEnabled`), Crashlytics can keep reports on device. The React Native Firebase JS helpers check the `isCrashlyticsCollectionEnabled` value at the time you call them:

- `checkForUnsentReports` resolves `true` when cached unsent reports exist. It **throws** synchronously if collection is enabled, because reports are sent automatically in that mode.
- `sendUnsentReports` returns `void` and calls into native only when collection is **enabled**. When collection is disabled it is a silent no-op.
- `deleteUnsentReports` discards cached reports on the device.
- `didCrashOnPreviousExecution` resolves whether the app crashed during the previous run.

```js
import {
  getCrashlytics,
  setCrashlyticsCollectionEnabled,
  checkForUnsentReports,
  sendUnsentReports,
  deleteUnsentReports,
  didCrashOnPreviousExecution,
} from '@react-native-firebase/crashlytics';

async function reviewQueuedReports() {
  const crashlytics = getCrashlytics();
  await setCrashlyticsCollectionEnabled(crashlytics, false);

  const crashedLastLaunch = await didCrashOnPreviousExecution(crashlytics);
  console.log('Crashed on previous execution:', crashedLastLaunch);

  // WARNING: checkForUnsentReports throws when Crashlytics collection is enabled.
  const hasUnsent = await checkForUnsentReports(crashlytics);
  if (hasUnsent) {
    // sendUnsentReports only reaches native when collection is enabled;
    // with collection disabled it is a silent no-op.
    await setCrashlyticsCollectionEnabled(crashlytics, true);
    sendUnsentReports(crashlytics);
  } else {
    await deleteUnsentReports(crashlytics);
  }
}
```

## Automatic JavaScript error reporting

Creating a Crashlytics instance installs two handlers, with no code needed on your side:

- A global JavaScript exception handler records unhandled exceptions with their JavaScript stack trace. See [Crashlytics Javascript stacktrace issue generation](/crashlytics/usage#crashlytics-javascript-stacktrace-issue-generation) and [exception handler chaining](/crashlytics/usage#crashlytics-javascript-exception-handler-chaining) for the `firebase.json` options that change this. If `@react-native-firebase/analytics` is installed, the handler also logs an `app_exception` Analytics event.
- A promise rejection tracker records unhandled promise rejections as non-fatal errors with a JavaScript stack trace. This only happens when `__DEV__` is `false`, so development builds do not report them.

The native module records nothing while Crashlytics collection is disabled.

# firebase.json

The `firebase.json` options below apply to Android and iOS. See [firebase.json](/app/json-config) for the full list of keys across packages.

## Disable Auto Collection

Additionally, you can configure whether Crashlytics sends out any reports through the `crashlytics_auto_collection_enabled` option in
your `firebase.json` config. If you want users to opt-in, it is recommended that you disable this here and enable it later
with `setCrashlyticsCollectionEnabled` once they opt-in. When the option is not set, collection is enabled in release builds.

```json
// <project-root>/firebase.json
{
  "react-native": {
    "crashlytics_auto_collection_enabled": false
  }
}
```

## Enable debug crash logs

Because you have stack traces readily available while you're debugging your app, Crashlytics collection is disabled in debug builds unless you set the `crashlytics_debug_enabled` option to `true` in your `firebase.json`. The option has no effect on release builds, and in a debug build it takes priority over `crashlytics_auto_collection_enabled` and `setCrashlyticsCollectionEnabled`.

```json
// <project-root>/firebase.json
{
  "react-native": {
    "crashlytics_debug_enabled": true
  }
}
```

## Crashlytics NDK

The React Native Firebase Android module depends on the Crashlytics NDK library, so [Crashlytics NDK](https://firebase.google.com/docs/crashlytics/ndk-reports) reporting is included in your app. It captures crashes in native C and C++ code.

Symbols for native libraries are not uploaded by default. To get readable native stack traces, enable `nativeSymbolUploadEnabled` as described in step 4 of [Android Setup](/crashlytics/android-setup#4-optional-enable-crashlytics-ndk-reporting) and run the symbol upload task after each build.

## Crashlytics Javascript stacktrace issue generation

React Native Crashlytics module by default installs a global javascript exception handler, and it records a crash with a javascript stack trace any time an unhandled javascript exception is thrown. Sometimes it is not desirable behavior since it might duplicate issues in combination with the default mode of javascript global exception handler chaining. We recommend leaving JS crashes enabled and turning off exception handler chaining. However, if you have special crash handling requirements, you may disable this behavior by setting the appropriate option to false.

When this option is `false` and chaining is also `false`, an unhandled javascript exception is neither recorded nor passed on to the previously installed handler.

```json
// <project-root>/firebase.json
{
  "react-native": {
    "crashlytics_is_error_generation_on_js_crash_enabled": false
  }
}
```

## Crashlytics Javascript exception handler chaining

React Native Crashlytics module's global javascript exception handler by default chains to any previously installed global javascript exception handler after logging the crash with the javascript stack trace. In default react-native setups, this means in development you will then see a "red box" and in release mode you will see a second native crash in the Crashlytics console with no javascript stack trace. These duplicate crash reports are probably not desirable, and the one from the chained handler will not have the javascript stack trace. We recommend disabling this once Crashlytics is integrated in testing. It is enabled by default, which makes initial integration testing easier. You may disable exception handler chaining by setting the appropriate option to false. With chaining disabled, the module records the error with its javascript stack trace and then terminates the app itself instead of passing the exception on.

```json
// <project-root>/firebase.json
{
  "react-native": {
    "crashlytics_javascript_exception_handler_chaining_enabled": false
  }
}
```

## Crashlytics non-fatal exceptions native handling

In case you need to log non-fatal (handled) exceptions on the native side (for example from a `try` / `catch` block), you may use the following static methods.

### Android

```java
import io.invertase.firebase.crashlytics.ReactNativeFirebaseCrashlyticsNativeHelper;

try {
  throw new Exception("Handled native failure");
} catch (Exception e) {
  ReactNativeFirebaseCrashlyticsNativeHelper.recordNativeException(e);
}
```

### iOS

```objectivec
#import <RNFBCrashlytics/RNFBCrashlyticsNativeHelper.h>

@try {
  @throw [NSException exceptionWithName:@"HandledNativeFailure"
                                 reason:@"Example handled native failure"
                               userInfo:nil];
} @catch (NSException *exception) {
  NSMutableDictionary *info = [NSMutableDictionary dictionary];
  [info setValue:exception.name forKey:@"ExceptionName"];
  [info setValue:exception.reason forKey:@"ExceptionReason"];
  [info setValue:exception.callStackReturnAddresses forKey:@"ExceptionCallStackReturnAddresses"];
  [info setValue:exception.callStackSymbols forKey:@"ExceptionCallStackSymbols"];
  [info setValue:exception.userInfo forKey:@"ExceptionUserInfo"];

  NSError *error = [[NSError alloc] initWithDomain:@"com.example.app" code:1 userInfo:info];
  [RNFBCrashlyticsNativeHelper recordNativeError:error];
}
```

# Package version

`SDK_VERSION` is the React Native Firebase Crashlytics package version string exported from `@react-native-firebase/crashlytics`. The firebase-js-sdk does not export `SDK_VERSION` from a Crashlytics entry point (there is no `@firebase/crashlytics` modular package).

```js
import { SDK_VERSION } from '@react-native-firebase/crashlytics';

console.log('Crashlytics package version:', SDK_VERSION);
```

The legacy `Statics` interface describes the old `firebase.crashlytics` statics shape that exposed `SDK_VERSION`. The entry point does not export it, so import `SDK_VERSION` from `@react-native-firebase/crashlytics`.
