---
title: FAQs and Tips
description: >-
  Troubleshooting: react-native-firebase vs firebase-js-sdk, New Architecture
  compatibility, CI build hangs, Analytics 'items' parameter,
  InternalFirebaseAuth.FIREBASE_AUTH_API errors, Crashlytics iOS crash testing
  under the Xcode debugger, in-app message testing, and iOS background message
  handling.
next: /ai/usage
previous: /platforms
---
> ## 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

These answers assume you already have (or are installing) React Native Firebase via [Getting Started](/): `@react-native-firebase/app` plus any product packages you use, with Android `google-services.json` / iOS `GoogleService-Info.plist` (or Expo `googleServicesFile` fields) in place. From v26, every package with a native bridge requires React Native's New Architecture.

Over the years, there’s been a lot of discussions on our [GitHub](https://github.com/invertase/react-native-firebase) and [Discord](https://invertase.link/discord). Many of them have been about common problems developers face when using our package, and some of them resulted in very good advice being given.

In order to save others time and frustration, this page has been created to document some of these common problems and good pieces of advice.
If you come across a discussion that results in great advice that can benefit many developers, or a discussion that resolves a problem that many developers encounter, please do add it here! Someone will definitely be grateful.

# FAQs

### Why `react-native-firebase` over `firebase-js-sdk`?

This package wraps `firebase-android-sdk` and `firebase-ios-sdk` into a Javascript API for React Native projects, so the main benefits come with the access to native code.

- There are more modules in the native SDKs than the web SDK because some things only make sense in a mobile / native context ( App Distribution, Crashlytics), so you can actually do more, and some of it is important for example, monitoring quality with Crashlytics

- Some of the modules that are both in the web SDK and native SDK have a great deal more functionality when they can harness native APIs, like messaging (with background delivery that can start your app if not running), like App Check where you can tie the attestation to device-level providers, Storage where you can do background downloads, Performance where you can start measurements from boot, etc.

For a platform matrix and the firebase-js-sdk fallback on web/macOS/Windows, see [Platforms](/platforms).

### Does it work with New Architecture / Fabric / TurboModules?

From v26, every React Native Firebase package with a native bridge is a Codegen TurboModule and **requires** React Native's New Architecture. Pure JavaScript packages such as `@react-native-firebase/ai` do not need New Architecture. See [Migrating to v26 — New Architecture requirement](/migrating-to-v26#new-architecture-requirement).

CI and maintainer testing run with New Architecture enabled. If you cannot enable New Architecture, stay on v25 (or earlier, if a package's own migration guide requires it).

### I need help with [anything regarding v5 or earlier of React Native Firebase]. Where could I get help with that?

React Native Firebase v5 is deprecated and unsupported. A long grace period was provided to migrate to v6, so maintainers are unlikely to spend time on v5 issues. Understandably, upgrading to v6 can take some effort, but staying on v5 is a poor choice for the long-term health of your project.
Lots of the breaking changes that were introduced were either due to upstream deprecations in the official SDKs, or to simply make the package more stable and more representative of how the actual SDKs work.
The longer you stay on v5, the more your project will be out of sync with the official SDKs. Couple that with the fact that it's no longer actively supported, and that is trouble for your project.

We highly recommend taking the necessary pains to update to a supported major (v6 or later; from v26 you also need New Architecture for native modules).

### My CI build hangs at the "Running script '[CP-User] [RNFB] Core Configuration'" step

This may be fixed by creating a `firebase.json` file at the root of your project if it's not there already. Create it before the next CI or native build that runs the Core Configuration script. If you don't want to change any of the default React Native Firebase configurations, you can leave the React Native section empty:

```json
{
  "react-native": {}
}
```

### I have a custom Analytics parameter called 'items' and it's not showing up on the Firebase console. How come?

This is a known problem with the upstream Analytics SDKs, and the fix is on their side rather than in React Native Firebase. Details are in [issue #4018](https://github.com/invertase/react-native-firebase/issues/4018#issuecomment-682174087).

### I'm receiving `InternalFirebaseAuth.FIREBASE_AUTH_API is not available on this device`. How do I fix this?

To use some Firebase services (like auth) in an emulator, you need an Android virtual device with Google Play services installed. Check this [Stack Overflow post](https://stackoverflow.com/a/46246782/2275865) for instructions on creating a new Android virtual device with the necessary APIs installed.

### Xcode stops on a crash line in `RNFBCrashlyticsModule.mm` when faking a crash on iOS. How do I fix this?

`crash(getCrashlytics())` deliberately crashes the app. With the debugger attached, Xcode can stop at the crashing line in the library source under `node_modules` (not app code you edit), and Crashlytics does not receive the report. The native `crash` method writes through a null pointer:

```objectivec
// Library source (RNFB Crashlytics, RNFBCrashlyticsModule.mm). Shown for orientation only; do not copy into your app.
- (void)crash {
  if ([RNFBCrashlyticsInitProvider isCrashlyticsCollectionEnabled]) {
    if ([self isDebuggerAttached]) {
      RCTLog(@"Crashlytics - WARNING: Debugger detected. Crashlytics will not receive crash reports.");
    }

    int *p = 0;
    *p = 0;
  } else {
    RCTLog(@"Crashlytics - INFO: crashlytics collection is not enabled, not crashing.");
  }
}
```

If Crashlytics collection is disabled, `crash` skips the crash and only logs `Crashlytics - INFO: crashlytics collection is not enabled, not crashing.`

The module logs `Debugger detected. Crashlytics will not receive crash reports.` when it sees an attached debugger. To test a real crash report, run the app without the Xcode debugger attached, for example by clearing "Debug executable" under 'Project name' -> 'Edit Scheme...' -> 'Run' -> 'Info', or by stopping the debug session and relaunching the installed app from the device or simulator.

### I have the SDK installed, but I can't send a test in app message from the console. How do I fix this?

Sometimes when building an in-app-message in the console, sending a test to a device is not possible, as the "Test on device" button is grayed out. This can be very annoying, but have found a "work around" that enables the button:

1. Make sure to fill out all fields in the first step of the form. If that doesn't enable the button:
1. Make sure to click inside every field, even if the field does not need to be updated (specially the "Text color" ones). If that doesn't enable the button:
1. Change between the "Message layout" options (Card, Modal, Image only and Top banner).

Sometimes, after step 3, you have to click inside a "Text color" field, but this should enable the "Test on device" option. After that you add the device Install ID, make sure to quit the app before the actual test, and then I wait for the confirmation toast to open the app up again. As long as the ID is 100% correct, the test should work as intended.

### On iOS, when the app is in quit state, the setBackgroundMessageHandler is never invoked even when I receive the notification. How can I fix this?

When the app is closed/quit, this can happen even when you are getting notifications and even when you are able to invoke the app in a headless state.

Prerequisites for this answer: `@react-native-firebase/messaging` installed and linked, APNs configured, and a background message handler registered as documented in [Cloud Messaging](/messaging/usage).

To fix this:

1. You first need to send the payload with "content-available: 1" in the `apns` section of the message payload so the app gets invoked in a headless state.
2. On the `index.js` page, if the app is invoked in headless mode, instead of returning null, return a simple component that does nothing and renders nothing. Otherwise, return the actual `App` component.

To view the complete detail for this solution, please refer to this page: [#5656](https://github.com/invertase/react-native-firebase/issues/5656)

# Tips

- Whenever you face a strange issue (or an issue that causes build errors), there are two things you should always consider.
  - Build processes are costly and complex, so caching is used a lot. As a result, certain changes that you make in your app can cause cache conflicts in subsequent builds. Deal with this via `npx react-native-clean-project`. This does solve a lot of problems.
  - Try and isolate the problem with a template React Native Firebase app. This [bash script](https://github.com/mikehardy/rnfbdemo/blob/main/make-demo.sh) is particularly helpful in making an empty template app.
- Advice on supporting multiple environments (for example, dev, prod, maybe also staging, qa) for your React Native Firebase App: [#3504](https://github.com/invertase/react-native-firebase/issues/3504)
- Using [Fastlane for iOS deployment](https://docs.fastlane.tools/getting-started/ios/setup/) together with [RN Firebase Crashlytics](/crashlytics/usage) within CI has been observed to cause builds that hang indefinitely. Using `setup_ci(force: true)` before building the application may solve the issue.: [#3706](https://github.com/invertase/react-native-firebase/issues/3706)
- Be careful if you are using a VPN, Google blocks many VPN IPs causing "unavailable" errors for various firebase API calls, and on an Android emulator it might completely mess up the network adapter causing network calls to never return, not only on firebase but on the entire emulated phone.
