Troubleshooting Common Issues

This guide covers common issues you might encounter when developing React Native applications and their solutions.

Build Errors

Module not found / Cannot resolve module

Symptoms:

error: Error: Unable to resolve module `./MyComponent`
Module does not exist in the Haste module map

Solutions:

Clear Metro cache:
```
npx react-native start --reset-cache
```

Check import path:

// ❌ Wrong
import MyComponent from './myComponent'; // Case mismatch

// ✅ Correct
import MyComponent from './MyComponent';

Clear node_modules and reinstall:
```
rm -rf node_modules
npm install
```

Check file extension:

// If file is MyComponent.tsx
import MyComponent from './MyComponent'; // .tsx not needed

Watchman issues:
```
watchman watch-del-all
```

iOS build fails: Pod install errors

Symptoms:

[!] CocoaPods could not find compatible versions for pod
Unable to install required dependencies

Solutions:

Update CocoaPods:
```
sudo gem install cocoapods
```

Deintegrate and reinstall:

cd ios
pod deintegrate
pod install
cd ..

Update pod repo:

pod repo update
pod install --repo-update

Clear CocoaPods cache:

rm -rf ~/Library/Caches/CocoaPods
rm -rf Pods
rm Podfile.lock
pod install

Check Podfile platform version:

# ios/Podfile
platform :ios, '13.4' # Must meet minimum requirement

Android build fails: Gradle errors

Symptoms:

FAILURE: Build failed with an exception
Could not resolve all dependencies

Solutions:

Clean Gradle:
```
cd android
./gradlew clean
cd ..
```

Clear Gradle cache:

cd android
./gradlew cleanBuildCache
rm -rf ~/.gradle/caches/
cd ..

Update Gradle version:

# android/gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip

Check Android SDK:
- Open Android Studio
- SDK Manager → Install required SDK versions
- Set ANDROID_HOME environment variable
Sync project with Gradle files in Android Studio

'React/RCTBridgeModule.h' file not found

Symptoms:

'React/RCTBridgeModule.h' file not found
'React/RCTEventEmitter.h' file not found

Solutions:

Clean and reinstall:

cd ios
rm -rf Pods Podfile.lock
pod install
cd ..

Clear Xcode derived data:

rm -rf ~/Library/Developer/Xcode/DerivedData/*

Clean build folder in Xcode:
- Product → Clean Build Folder (Cmd + Shift + K)
Check Header Search Paths in Xcode:
- Build Settings → Header Search Paths
- Should include $(SRCROOT)/../node_modules/react-native/React

Runtime Errors

Red screen: Invariant Violation

Symptoms:

Invariant Violation: Element type is invalid
Invariant Violation: View config getter callback must be a function

Solutions:

Check component imports:

// ❌ Wrong
import Button from 'react-native';

// ✅ Correct
import {Button} from 'react-native';

Verify component exports:

// Component.js
export default function MyComponent() { /* ... */ }

// Usage
import MyComponent from './Component';

Check for circular dependencies

Ensure component is properly defined:

// ❌ Wrong
const MyComponent = () => {
  return (
    <View>
    // Missing closing tag
  );
};

// ✅ Correct
const MyComponent = () => {
  return (
    <View>
      <Text>Hello</Text>
    </View>
  );
};

Network request failed

Symptoms:

Network request failed
TypeError: Network request failed

Solutions:

Check network connectivity

Allow HTTP on iOS (development only):

<!-- ios/MyApp/Info.plist -->
<key>NSAppTransportSecurity</key>
<dict>
  <key>NSAllowsArbitraryLoads</key>
  <true/>
</dict>

Check Android network permissions:

<!-- android/app/src/main/AndroidManifest.xml -->
<uses-permission android:name="android.permission.INTERNET" />

Use correct localhost address:
- iOS Simulator: http://localhost:3000
- Android Emulator: http://10.0.2.2:3000
- Physical device: Use computer’s IP address
Check CORS on backend

Verify API endpoint:

// Test with curl first
// curl https://api.example.com/endpoint

White screen on launch

Symptoms:

App shows white/blank screen
No errors in console

Solutions:

Check Metro bundler is running:
```
npx react-native start
```
Reload JavaScript:
- iOS: Cmd + R
- Android: Press R twice or Cmd/Ctrl + M → Reload

Check App.js/index.js:

// index.js
import {AppRegistry} from 'react-native';
import App from './App';
import {name as appName} from './app.json';

AppRegistry.registerComponent(appName, () => App);

Check for JavaScript errors:
- Open React Native Debugger
- Check console for errors

Verify root component renders:

// App.js
import React from 'react';
import {SafeAreaView, Text} from 'react-native';

function App() {
  return (
    <SafeAreaView>
      <Text>Hello World</Text>
    </SafeAreaView>
  );
}

export default App;

App crashes on launch (native crash)

Symptoms:

App crashes immediately
No JavaScript error

Solutions:

Check native logs: iOS:

# View device logs
xcrun simctl spawn booted log stream --level=debug

Android:

adb logcat

Clean and rebuild:

# iOS
cd ios
rm -rf build
xcodebuild clean
cd ..
npx react-native run-ios

# Android
cd android
./gradlew clean
cd ..
npx react-native run-android

Check native module compatibility:
- Verify all native modules support your React Native version
- Update or remove incompatible modules

Reinstall native dependencies:

rm -rf node_modules
npm install
cd ios && pod install && cd ..

Performance Issues

Slow navigation / UI lag

Symptoms:

Slow screen transitions
Laggy animations
Dropped frames

Solutions:

Enable Hermes: iOS (ios/Podfile):

:hermes_enabled => true

Android (android/app/build.gradle):

project.ext.react = [
  enableHermes: true
]

Use React.memo for expensive components:

const MyComponent = React.memo(({data}) => {
  return <View>{/* ... */}</View>;
});

Optimize FlatList:

<FlatList
  data={data}
  renderItem={renderItem}
  keyExtractor={item => item.id}
  removeClippedSubviews={true}
  maxToRenderPerBatch={10}
  updateCellsBatchingPeriod={50}
  initialNumToRender={10}
  windowSize={10}
/>

Use InteractionManager:

InteractionManager.runAfterInteractions(() => {
  // Expensive operation after navigation completes
  this.setState({dataLoaded: true});
});

Profile with React DevTools Profiler

High memory usage

Symptoms:

App crashes with out of memory
Slow performance over time

Solutions:

Optimize images:

// Use appropriate image sizes
<Image
  source={{uri: imageUrl}}
  style={{width: 100, height: 100}}
  resizeMode="cover"
/>

// Use react-native-fast-image for better caching
import FastImage from 'react-native-fast-image';

<FastImage
  source={{uri: imageUrl}}
  style={{width: 100, height: 100}}
  resizeMode={FastImage.resizeMode.cover}
/>

Clean up listeners and timers:

useEffect(() => {
  const subscription = eventEmitter.addListener('event', handler);
  
  return () => {
    subscription.remove();
  };
}, []);

Limit list rendering:
- Use FlatList instead of ScrollView for long lists
- Implement virtualization
- Remove items outside viewport
Monitor with Performance Monitor:
- Shake device → Show Performance Monitor
- Watch Memory usage

Metro Bundler Issues

Metro bundler stuck at loading

Symptoms:

Loading dependency graph...
(stuck indefinitely)

Solutions:

Reset cache:
```
npx react-native start --reset-cache
```
Clear watchman:
```
watchman watch-del-all
```

Clear Metro cache:

rm -rf $TMPDIR/metro-*
rm -rf $TMPDIR/haste-map-*

Increase Node memory:

NODE_OPTIONS=--max_old_space_size=4096 npx react-native start

Check for circular dependencies

Port already in use

Symptoms:

ERROR  EADDRINUSE: address already in use :::8081

Solutions:

Kill process on port 8081: macOS/Linux:

lsof -ti:8081 | xargs kill -9

Windows:

netstat -ano | findstr :8081
taskkill /PID <PID> /F

Use different port:

npx react-native start --port 8088

Then run app with custom port:

RCT_METRO_PORT=8088 npx react-native run-ios

Debugging Tools

React DevTools not connecting

Solutions:

Ensure React DevTools is running:
```
npx react-devtools
```
Reload app after opening DevTools
Check firewall settings
Try different port:
```
npx react-devtools --port 8098
```

Chrome debugger disconnecting

Solutions:

Use Hermes debugger instead:
- Shake device → “Debug with Chrome” becomes “Hermes Debugger”
Disable Chrome extensions
Clear Chrome cache

Use Flipper instead:

npx react-native-community/cli doctor
# Install Flipper if suggested

Environment Issues

Command not found: react-native

Solutions:

Use npx:
```
npx react-native <command>
```
Install globally (not recommended):
```
npm install -g react-native-cli
```

Add to PATH:

export PATH="$PATH:./node_modules/.bin"

Node/npm version issues

Solutions:

Check Node version:

node --version  # Should be v18+ or v22+ for RN 0.84+

Update Node using nvm:

nvm install 22
nvm use 22
nvm alias default 22

Clear npm cache:
```
npm cache clean --force
```

Testing Issues

Jest tests failing with module errors

Solutions:

Configure Jest transform:

// jest.config.js
module.exports = {
  preset: 'react-native',
  transformIgnorePatterns: [
    'node_modules/(?!(@react-native|react-native|react-native-.*)/)',
  ],
};

Mock native modules:

// __mocks__/react-native.js
const ReactNative = require('react-native');

ReactNative.NativeModules = {
  ...ReactNative.NativeModules,
  // Mock your native modules
};

module.exports = ReactNative;

Clear Jest cache:
```
jest --clearCache
```

Getting Help

When seeking help:

Provide error logs:
- Full error message
- Stack trace
- Metro bundler output
Share environment info:
```
npx react-native info
```
Create minimal reproduction:
- Isolate the issue
- Share code that reproduces the problem
Check existing issues:
- React Native GitHub Issues
- Stack Overflow
- React Native Community

Getting Started

Core Concepts

Architecture

Native Modules

Platform Guides

Performance

Developer Tools

Advanced Guides

Troubleshooting Common Issues

Build Errors

Runtime Errors

Performance Issues

Metro Bundler Issues

Debugging Tools

Environment Issues

Testing Issues

Getting Help

Next Steps

Debugging

Upgrading

Build docs developers (and LLMs) love

Getting Started

Core Concepts

Architecture

Native Modules

Platform Guides

Performance

Developer Tools

Advanced Guides

Documentation Index

​Build Errors

​Runtime Errors

​Performance Issues

​Metro Bundler Issues

​Debugging Tools

​Environment Issues

​Testing Issues

​Getting Help

​Next Steps

Debugging

Upgrading

Build docs developers (and LLMs) love

Build Errors

Runtime Errors

Performance Issues

Metro Bundler Issues

Debugging Tools

Environment Issues

Testing Issues

Getting Help

Next Steps