## Intro React Native lets you build mobile apps with JavaScript, but errors can surface at every layer - bundling, runtime, native modules, or build tooling. A methodical approach turns panic into a quick fix: identify the environment, reproduce the error, make one change, and verify the result. This guide walks through common React Native errors with practical, copy-paste commands and recovery steps. We will cover React Native CLI and Expo workflows, because both share many failure modes but differ in tooling. Each section includes read-only diagnostics, the smallest fix, and a verification check. Use placeholders instead of real credentials in any command you run, and keep a record of state changes for easy rollback. ## Version and Environment Inventory Before touching code, establish the ground truth. Many errors are version mismatches in disguise. ### Read-Only Observations Run the following commands in the project root and record the output: node --version npm --version npx react-native --version Example output: node: v18.17.1 npm: 9.6.7 react-native: npx: installed 1 in 2.3s React Native version: 0.72.5 For Expo projects, check: npx expo --version Also inspect package.json for react-native and key dependencies, and android/build.gradle for the Android Gradle Plugin version and compileSdkVersion . ### Environment Variables and Paths Verify that the Android SDK is properly set up (for React Native CLI): echo $ANDROID_HOME adb --version Expected: $ANDROID_HOME points to a valid SDK directory, and adb returns a version string. If ANDROID_HOME is not set, add it to your shell profile ( ~/.bashrc or ~/.zshrc ): export ANDROID_HOME=$HOME/Library/Android/sdk # macOS example export PATH=$PATH:$ANDROID_HOME/emulator export PATH=$PATH:$ANDROID_HOME/platform-tools Then reload with source ~/.zshrc (or your profile). For iOS, verify Xcode command line tools and CocoaPods: xcode-select --version pod --version If CocoaPods is missing, install with sudo gem install cocoapods . ### Blast Radius and Recovery Document the current state in a local file, e.g., env-snapshot-YYYYMMDD.txt , with: - Node, npm, React Native, Expo versions - package.json dependency ranges - Android SDK location and platform tools version - Any recent changes to environment variables or native project files This snapshot becomes your rollback reference. If a change breaks the build, revert the specific change before debugging further. ## Safe Configuration Path Configuration errors are among the most common, especially after upgrading React Native or adding native modules. Follow this path to change settings safely. ### Step 1: Locate Current Configuration For Metro bundler configuration, inspect metro.config.js : cat metro.config.js For Babel, check babel.config.js . For native projects, check android/build.gradle and ios/Podfile . ### Step 2: Make One Change at a Time Suppose you need to add support for SVG assets. You would install react-native-svg and link it. Instead of guessing, follow these steps: npm install react-native-svg cd ios && pod install && cd .. Verify the install by checking package.json and Podfile.lock . If you need to modify Metro configuration to include asset extensions, make a minimal change: // metro.config.js const { getDefaultConfig } = require('metro-config'); module.exports = (async () => { const { resolver: { assetExts } } = await getDefaultConfig(); return { resolver: { assetExts: [...assetExts, 'svg'] } }; })(); Restart Metro with npx react-native start --reset-cache . ### Step 3: Verify and Rollback After the change, run the app and test the specific feature. If problems arise, revert the configuration file (use version control) and restart Metro. For a rollback example, suppose you added svg to assetExts but it caused a different asset type to fail. Run: git checkout metro.config.js npx react-native start --reset-cache This restores the previous state. ### Precaution: Protect Secrets Never hard-code API keys or tokens in configuration files. Use environment variables or a secrets manager. For example, in React Native, you can use react-native-config : npm install react-native-config Then create .env (add to .gitignore ): API_URL=https://api.example.com Access in code: import Config from 'react-native-config'; const apiUrl = Config.API_URL; ## Verification and Diagnostics Verification separates a real fix from a lucky retry. Always define the expected result before running a command. ### Check Bundler Status Start Metro with verbose logging: npx react-native start --verbose Look for lines like: BUNDLE ./index.js If you see an error, capture the full stack trace. ### Test a Minimal Component Create a temporary screen with a simple component to isolate issues: // tempTest.js import React from 'react'; import { View, Text } from 'react-native'; export default function TempTest() { return ( Test OK ); } Import this as the initial route. If it renders, the problem is likely in your custom component or data. ### Use React Native Debugger For runtime errors, open the in-app developer menu (Cmd+D on iOS, Cmd+M on Android emulator) and select "Debug". Use Chrome DevTools or React Native Debugger to inspect logs and state. For Android, check device logs: adb logcat Filter for React Native errors: adb logcat *:S ReactNative:V ReactNativeJS:V Expected output includes JS console logs and red box errors. ### Automated Checks Run linting and tests before and after changes: npm run lint npm test Example passing output: PASS __tests__/App.test.js renders correctly ✓ renders correctly (312 ms) ## Failure Modes and Recovery Here are common failure modes, their symptoms, causes, and step-by-step fixes. ### 1. Metro Bundler "Unable to resolve module" Symptom: Build fails with error like: Unable to resolve module `./src/components/Button` from `src/screens/Home.js` Likely cause: Incorrect import path, missing file extension, or stale cache. Fix: - Check the file exists and the path is correct (case-sensitive on Linux CI). - Clear Metro cache: npx react-native start --reset-cache . - Delete node_modules and reinstall if dependency is missing: rm -rf node_modules npm install Verify: Re-run the build and confirm the module resolves. ### 2. Android Build Failure: "Could not find com.android.tools.build:gradle" Symptom: Gradle sync fails with missing plugin. Fix: Ensure the Google Maven repository is in android/build.gradle : buildscript { repositories { google() mavenCentral() } dependencies { classpath("com.android.tools.build:gradle:7.4.2") } } Then run: cd android && ./gradlew clean && cd .. Verify: ./gradlew assembleDebug completes successfully. ### 3. iOS Pod Install Failure Symptom: pod install fails with "CocoaPods could not find compatible versions for pod 'React-Core'". Fix: - Delete Podfile.lock and Pods folder. - Run pod repo update and pod install --repo-update . - If still failing, check ios/Podfile for platform version. Ensure it matches React Native requirements (usually platform :ios, '12.4' or higher). Verify: pod install completes and the app builds in Xcode. ### 4. "Invariant Violation: requireNativeComponent: 'RNSVGPath' was not found in the UIManager" Symptom: Runtime red box error for a native component. Fix: Usually a linking issue. For React Native 0.60+ autolinking should work. If not, manually link: - Android: check settings.gradle includes the library. - iOS: run cd ios && pod install && cd .. . - Rebuild the app: npx react-native run-ios or npx react-native run-android . Verify: Component renders without error. ### 5. "Unable to load script. Make sure you're either running a Metro server or that your bundle 'index.android.bundle' is packaged correctly for release" Symptom: App shows this error on startup, often on a physical device. Fix for debug: - Ensure Metro is running ( npx react-native start ). - On device, set debug server host to your machine's IP: in developer menu, "Settings" > "Debug server host & port for device", enter 192.168.1.100:8081 (replace with your IP). - Alternatively, run adb reverse tcp:8081 tcp:8081 for Android via USB. Fix for release: - Bundle the JS into the APK/IPA: npx react-native bundle --platform android --dev false --entry-file index.js --bundle-output android/app/src/main/assets/index.android.bundle --assets-dest android/app/src/main/res Then rebuild release. Verify: App loads without network dependency. ### Recovery Principles - Always keep a snapshot of working configurations. - Use version control and commit before making risky changes. - If a fix introduces a new issue, revert immediately and analyze later. ## Operations Checklist Use this checklist before and after any change to prevent common errors and ensure recoverability.
StepActionOwnerFrequencyVerification
1Record current environment (Node, RN, SDK)Developer (e.g., Priya Shah, Engineering Lead)Before each changeenv-snapshot.txt created and reviewed
2Sync dependencies to lockfileDeveloperWeeklynpm ci completes with no errors
3Clear caches if bundler misbehavesDeveloperAs needednpx react-native start --reset-cache starts successfully
4Run lint and testsDeveloperBefore commitnpm run lint && npm test passes
5Build debug app locallyDeveloperBefore merging PRnpx react-native run-android or run-ios launches app
6Verify native module linking after adding dependenciesDeveloperAfter each new native moduleComponent using the module renders without native error
7Check Android SDK and environment variablesDevOps / Build Engineer (e.g., Mark Chen, DevOps)Monthlyecho $ANDROID_HOME returns correct path; adb devices lists device
8Review crash logs and analyticsMobile LeadWeeklyCrash-free sessions > 99.5%
Each item has a single accountable owner and a clear frequency. Adjust owners to your team, but keep accountability explicit. ## Common Pitfalls and How to Avoid Them Many repeated mistakes stem from skipping environment checks or caching layers. ### Pitfall 1: Ignoring Version Mismatches Why it happens: Copying commands from outdated tutorials or mixing React Native versions after an upgrade. How to avoid: Always check npx react-native --version and consult the official upgrade helper for your target version. Never mix native code from different React Native versions. Recovery: If a version mismatch caused a build failure, revert to a known-good commit, then upgrade stepwise using npx react-native upgrade . ### Pitfall 2: Not Clearing Caches Why it happens: Metro bundler and Gradle/Pod caches become stale after dependency changes. How to avoid: After changing dependencies, run: watchman watch-del-all rm -rf node_modules && npm install cd android && ./gradlew clean && cd .. cd ios && pod deintegrate && pod install && cd .. Recovery: If you forget and run into odd bundling errors, run the cache-clearing sequence above before deeper debugging. ### Pitfall 3: Hardcoding Secrets Why it happens: Quick prototyping leads to keys baked into code, then forgotten. How to avoid: Use environment variables from day one. Add .env to .gitignore and use a secrets manager for production. Recovery: If a secret was committed, revoke it immediately, rotate credentials, and scrub git history using a tool like git-filter-repo . Then set up proper environment injection. ### Pitfall 4: Skipping Verification After Fixes Why it happens: Time pressure; the error disappears, so it's assumed fixed. How to avoid: Always run the specific command or test that previously failed. For UI errors, manually test the screen. For build errors, rebuild from clean state. Recovery: If a fix has unintended side effects, use your environment snapshot and version control to revert, then approach the problem with a smaller change. ### Pitfall 5: Using a Global Watchman That Conflicts Why it happens: Multiple React Native projects with different watchman versions or permissions cause file watching to fail. How to avoid: Use project-local watchman or ensure watchman is up to date: brew upgrade watchman # macOS Recovery: If watchman errors appear, run watchman watch-del-all and restart Metro. ## Conclusion React Native errors are rarely mysterious once you trace them to their layer: environment, configuration, bundling, or native build. This guide gave you concrete commands and checklists to diagnose and fix common issues. The key is discipline: observe first, change one thing at a time, verify, and keep a rollback path. Start with one low-risk verification from this article, such as running npx react-native --version and documenting your environment. Then, when the next error appears, you will already have a baseline. Remember to review dependencies like Expo, Android SDK, and native modules as part of your troubleshooting routine. A reliable workflow makes failures visible, protects sensitive values, limits changes to the intended resource, and defines recovery before an incident forces the decision.