Skip to main content

React Native App Troubleshooting

Use this guide when an Instamobile React Native app does not install, bundle, build, connect to Metro, or load data correctly.

Quick Answer​

Start with the smallest reset that matches the problem. Install dependencies, restart Metro with a clean cache, reinstall iOS pods after native dependency changes, verify Android SDK/device setup, and inspect Firebase errors before changing app code.

corepack enable
yarn install
yarn start --reset-cache

For iOS:

bundle exec pod install --project-directory=ios
yarn ios

For Android:

yarn android

Before You Debug​

Run commands from the app folder that contains package.json, ios/, android/, and src/.

Check the basics first:

node --version
yarn --version
git status --short

If the app package includes an .nvmrc, use it:

nvm use

Avoid deleting lockfiles or native folders as a first step. Most errors can be fixed with a targeted cache reset, pod install, SDK check, or Firebase config change.

Detailed Troubleshooting Guides​

Use the dedicated guide that matches the failing layer:

Problem areaGuide
Metro, bundling, cache, module resolution, WatchmanMetro and Bundler Errors
iOS, Xcode, CocoaPods, pods, Node pathiOS and CocoaPods Errors
Android, Gradle, SDK, emulator, adbAndroid and Gradle Errors
Firebase Auth, Firestore, Storage, Functions, App CheckFirebase Errors

Metro and Bundler Issues​

No Bundle URL Present​

This usually means the app cannot connect to Metro.

  1. Stop all running Metro terminals.
  2. Start Metro from the correct app folder:
yarn start --reset-cache
  1. Reload the app from the simulator or device.
  2. Rebuild the app if it still points to an old bundle.

React Native Version Mismatch​

This usually happens when Metro is running from another project.

  1. Stop Metro.
  2. Close other React Native terminals.
  3. Start Metro from the current app folder:
yarn start --reset-cache
  1. Rebuild iOS or Android.

App Gets Stuck on the Splash Screen​

If the native app builds but stays on the launch screen, Metro may not be serving the JavaScript bundle.

yarn start --reset-cache

Then rebuild:

yarn ios

or:

yarn android

If the app uses Firebase, also check that your config files are present and that the first screen is not waiting on a failing backend request.

Watchman Recrawl Warning​

If Metro warns that Watchman recrawled the project, reset the watch from the repository root:

watchman watch-del .
watchman watch-project .

Then restart Metro.

iOS, Xcode, and CocoaPods Issues​

Pods Are Out of Sync​

Run pod install after changing native dependencies:

bundle exec pod install --project-directory=ios

If the app package has no Gemfile, run:

cd ios
pod install
cd ..

Xcode Cannot Find Node​

Some React Native projects support ios/.xcode.env.local for local Node path overrides.

Create this file only on your machine:

export NODE_BINARY=/opt/homebrew/bin/node

Do not commit ios/.xcode.env.local.

Xcode Derived Data Is Stale​

Clean the build folder from Xcode. If the issue persists, delete Derived Data from Xcode settings and rebuild.

Missing GoogleService-Info.plist​

Firebase-backed apps need GoogleService-Info.plist in the iOS target.

Download it from Firebase Console and place it where the app expects it. Then reinstall pods if the native project references changed files:

bundle exec pod install --project-directory=ios

Android and Gradle Issues​

Activity Class Does Not Exist​

If the terminal shows BUILD SUCCESSFUL, the app may still be installed even if React Native CLI could not open it automatically.

Check the emulator or device app drawer and open the app manually. If it is not installed, rerun:

yarn android

SDK Location Not Found​

Android cannot find your SDK path. Open Android Studio SDK Manager and confirm that SDK Platform Tools are installed.

If needed, add Android tools to your shell profile:

export ANDROID_HOME="$HOME/Library/Android/sdk"
export PATH="$ANDROID_HOME/platform-tools:$PATH"

Restart the terminal and verify:

adb devices

No Device Is Detected​

Start an emulator or connect a physical device with USB debugging enabled:

adb devices

If a physical device is unauthorized, reconnect it and accept the debugging prompt on the device.

Gradle Cache Is Stale​

Clean the Android build:

cd android
./gradlew clean
cd ..

Then restart Metro and rebuild:

yarn start --reset-cache
yarn android

Missing google-services.json​

Firebase-backed apps need android/app/google-services.json.

Download it from Firebase Console and place it in the Android app module before running:

yarn android

Missing debug.keystore​

React Native debug builds normally use a debug keystore under the Android app folder. If it is missing, generate one with keytool:

keytool -genkeypair -v \
  -storetype PKCS12 \
  -keystore android/app/debug.keystore \
  -storepass android \
  -alias androiddebugkey \
  -keypass android \
  -keyalg RSA \
  -keysize 2048 \
  -validity 10000 \
  -dname "CN=Android Debug,O=Android,C=US"

Then rerun:

yarn android

Firebase Issues​

Permission Denied​

This usually means Firestore or Storage rules do not allow the current user or path.

Check:

  • the user is signed in;
  • the document path matches the rule;
  • the write payload includes required fields;
  • you deployed your own rules to your Firebase project.

Missing Firestore Index​

Firestore may reject a query that needs a composite index. The error usually includes a Firebase Console link for creating the index.

Open that link, create the index, wait until it finishes building, then retry the app.

If the app package includes firestore.indexes.json, deploy indexes from the Firebase project folder:

firebase deploy --only firestore:indexes

Network Request Failed During Media Upload​

This can happen when Firebase Storage rules, config files, network access, or project billing are not ready.

Check:

  • GoogleService-Info.plist and google-services.json belong to your Firebase project;
  • Firebase Storage is enabled;
  • Storage rules allow the authenticated upload path;
  • the app has photo/media permissions;
  • the upload file URI exists on the device;
  • Cloud Functions used by upload processing are deployed;
  • the Firebase project plan supports the backend services used by the app.

Cloud Functions Return Internal Errors​

Check the Firebase Functions logs first:

firebase functions:log

Common causes:

  • missing environment variables or secrets;
  • wrong Firebase project selected;
  • function region mismatch;
  • unauthenticated callable request;
  • third-party API key missing or invalid;
  • billing not enabled for services that require it.

Push Notification Issues​

If push notifications do not arrive, verify:

  • Firebase Messaging is enabled and configured;
  • iOS APNs key/certificate is configured in Firebase;
  • Android notification permissions are requested when required;
  • the app obtains and saves a device token;
  • the backend sends to the correct token;
  • the app uses your Firebase config files.

Push notification setup is platform-specific. Use the push notification docs for the full flow.

Payment Issues​

If payments fail, do not place private payment keys in the mobile app.

Check:

  • public keys are in mobile config where required;
  • secret keys are in backend Functions or server environment variables;
  • Apple Pay or Google Pay is configured for the platform;
  • the backend creates payment intents or checkout sessions;
  • Firebase Functions or payment backend logs show the real provider error.

Media and Image Picker Issues​

If the image picker, camera, or media upload flow fails:

  • confirm native permissions are configured for iOS and Android;
  • rebuild the app after permission or native package changes;
  • test on a real device if the simulator lacks the capability;
  • check that selected media has a valid local URI;
  • inspect Firebase Storage or backend upload errors separately from picker errors.

What To Send Support​

When asking for help, include:

  • app name and Instamobile product version, if available;
  • exact command that failed;
  • terminal output around the error;
  • screenshot of the simulator/device error;
  • node --version;
  • yarn --version;
  • Xcode version for iOS issues;
  • Android Studio, SDK, and device/emulator details for Android issues;
  • whether the app was modified or still in its original downloaded state;
  • Firebase project service involved, if the error is backend-related.

Do not send private API keys, Firebase service account files, signing keys, or payment secrets.

FAQ​

Should I delete node_modules and lockfiles?​

Only as a last resort. Start with yarn install, yarn start --reset-cache, pod install, or a platform-specific clean. Deleting lockfiles can change package versions and introduce new errors.

Should I use Xcode or the terminal for iOS?​

Use the terminal for the normal yarn ios workflow. Use Xcode when you need signing, capabilities, entitlements, detailed native logs, or App Store archive work.

Should I open Android Studio?​

Yes, when you need SDK Manager, Device Manager, Logcat, Gradle sync details, or Android signing configuration. For normal development, use yarn android.

Why does a Firebase error show as a generic app error?​

The app may show a user-friendly message while Firebase logs contain the real error code. Check Metro logs, device logs, Firebase Functions logs, Firestore rules, Storage rules, and missing indexes.

Next Steps​