Troubleshooting

Solutions to common issues encountered during Expo development.

Installation Issues

npm/yarn Installation Fails

Problem: Installation errors or timeouts Solutions:

Clear npm cache:

npm cache clean --force
rm -rf node_modules package-lock.json
npm install

Try yarn:
```
npm install -g yarn
yarn install
```

Check Node version:

node --version  # Should be 18.0.0 or higher

Use different registry:

npm config set registry https://registry.npmjs.org/

Expo CLI Not Found

Problem: command not found: expo Solutions:

Use npx:
```
npx expo start
```

Or install globally:

npm install -g expo-cli  # Legacy
# Modern Expo uses npx expo

Check package installation:
```
npm list expo
```

Metro Bundler Issues

Metro Won’t Start

Problem: Metro bundler fails to start Solutions:

Clear Metro cache:
```
npx expo start --clear
```

Check port availability:

# Kill process on port 8081
lsof -ti:8081 | xargs kill -9

# Or use different port
npx expo start --port 8082

Clear all caches:

rm -rf node_modules/.cache
rm -rf .metro
npx expo start --clear

Reinstall dependencies:

rm -rf node_modules package-lock.json
npm install

Module Resolution Errors

Problem: Unable to resolve module or Cannot find module Solutions:

Install missing package:
```
npx expo install package-name
```
Clear cache:
```
npx expo start --clear
```

Check import path case sensitivity:

// Wrong on Linux/macOS
import Component from './component';

// Correct (matches filename)
import Component from './Component';

Verify file extensions:

// Don't include extension in imports
import Component from './Component';

Check Metro config:

// metro.config.js
const config = getDefaultConfig(__dirname);
console.log(config.resolver.sourceExts);

Slow Bundle Performance

Problem: Metro bundling is very slow Solutions:

Use Hermes:
```
{ "expo": { "jsEngine": "hermes" } }
```

Limit watched folders:

// metro.config.js
config.watchFolders = [__dirname];

Disable source maps in dev:

config.serializer.sourceMapUrl = undefined;

Check for large files:

find . -type f -size +1M -not -path "./node_modules/*"

Build Errors

Native Module Linking Issues

Problem: Native module cannot be null or module not found Solutions:

Prebuild for development builds:

npx expo prebuild --clean
npx expo run:ios

Add config plugin:

{
  "expo": {
    "plugins": ["expo-camera"]
  }
}

Check package installation:

npx expo install --check
npx expo install --fix

Clear native build cache:

# iOS
cd ios && rm -rf Pods Podfile.lock && pod install && cd ..

# Android
cd android && ./gradlew clean && cd ..

iOS Build Failures

Problem: Xcode build fails Solutions:

Update CocoaPods:

sudo gem install cocoapods
cd ios && pod repo update && pod install && cd ..

Clean Xcode cache:

cd ios
rm -rf ~/Library/Developer/Xcode/DerivedData/*
xcodebuild clean

Reinstall pods:

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

Check Xcode version:

xcodebuild -version  # Should match requirements

Select Xcode command line tools:

sudo xcode-select --switch /Applications/Xcode.app/Contents/Developer

Android Build Failures

Problem: Gradle build fails Solutions:

Set JAVA_HOME:

export JAVA_HOME=$(/usr/libexec/java_home -v 17)

Clean Gradle cache:

cd android
./gradlew clean
rm -rf .gradle
cd ..

Update Gradle:

cd android
./gradlew wrapper --gradle-version=8.0

Check Android SDK:

echo $ANDROID_HOME  # Should point to SDK

Invalidate caches in Android Studio:
- File → Invalidate Caches → Invalidate and Restart

Runtime Errors

White Screen on Launch

Problem: App shows white/blank screen Solutions:

Check console for errors:
- View terminal output
- Check React DevTools
Common causes:
- JavaScript error in render
- Missing dependencies
- Incorrect import paths

Add error boundary:

import React from 'react';
import { Text } from 'react-native';

class ErrorBoundary extends React.Component {
  state = { hasError: false };
  
  static getDerivedStateFromError() {
    return { hasError: true };
  }
  
  componentDidCatch(error, info) {
    console.error('Error:', error, info);
  }
  
  render() {
    if (this.state.hasError) {
      return <Text>Something went wrong</Text>;
    }
    return this.props.children;
  }
}

App Crashes on Device

Problem: App crashes immediately on physical device Solutions:

Check device logs:

# iOS
xcrun simctl spawn booted log stream --level debug

# Android
adb logcat

Verify app permissions:
- Check Info.plist (iOS)
- Check AndroidManifest.xml (Android)

Test in release mode:

npx expo run:ios --configuration Release
npx expo run:android --variant release

Check native dependencies:
- Ensure all native modules are compatible
- Check minimum OS versions

Network Request Failures

Problem: API requests fail or timeout Solutions:

Check Network Inspector:
- Press Cmd+D (iOS) or Cmd+M (Android)
- Enable Network Inspector

iOS specific - App Transport Security:

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

Android specific - Cleartext traffic:

<!-- AndroidManifest.xml -->
<application
  android:usesCleartextTraffic="true">

Check CORS (web):
- Ensure API allows cross-origin requests

Development Build Issues

Development Build Won’t Connect

Problem: Can’t connect to Metro from development build Solutions:

Check network connectivity:
- Use same WiFi network
- Or use --tunnel flag
Manually set dev server URL:
- Shake device
- Settings → Dev Server URL
- Enter http://YOUR_IP:8081
Use tunnel mode:
```
npx expo start --tunnel
```
Check firewall:
- Allow port 8081
- Disable VPN if needed

EAS Build Failures

Problem: EAS build fails Solutions:

Check build logs:

eas build:list
# Click on failed build for logs

Validate eas.json:
```
eas build:configure
```
Test build locally first:
```
eas build --local --platform ios
```
Common issues:
- Missing credentials
- Incorrect bundle identifier
- Native dependency conflicts

Platform-Specific Issues

iOS Simulator Issues

Problem: Simulator not working or not listed Solutions:

Restart Simulator:

xcrun simctl shutdown all
xcrun simctl erase all

List available simulators:
```
xcrun simctl list devices
```
Install simulators:
- Xcode → Settings → Platforms
- Download iOS simulators
Reset Simulator:
- Device → Erase All Content and Settings

Android Emulator Issues

Problem: Emulator won’t start or is very slow Solutions:

Check virtualization:
- Enable Intel VT-x or AMD-V in BIOS
- Check with: grep -E "(vmx|svm)" /proc/cpuinfo
Use ARM image on M1/M2 Mac:
- Create ARM64 emulator in Android Studio
Increase emulator RAM:
- Android Studio → AVD Manager
- Edit device → Advanced → RAM: 4096MB

Cold boot emulator:

emulator -avd Pixel_4_API_31 -no-snapshot-load

Update & Version Issues

Incompatible Package Versions

Problem: Version conflicts between packages Solutions:

Check compatibility:
```
npx expo install --check
```
Fix automatically:
```
npx expo install --fix
```
Check Expo SDK version:
```
// package.json
"expo": "~54.0.0"
```

Upgrade SDK:

npx expo install expo@latest
npx expo install --fix

OTA Update Not Working

Problem: Updates not appearing on devices Solutions:

Check update configuration:

{
  "expo": {
    "runtimeVersion": "1.0.0",
    "updates": {
      "url": "https://u.expo.dev/..."
    }
  }
}

Verify runtime version compatibility:
- Update must match runtime version
- Check runtimeVersion in app.json

Force update check:

import * as Updates from 'expo-updates';

async function checkForUpdates() {
  const update = await Updates.checkForUpdateAsync();
  if (update.isAvailable) {
    await Updates.fetchUpdateAsync();
    await Updates.reloadAsync();
  }
}

Check update logs:
```
eas update:list
```

Web-Specific Issues

Web App Won’t Start

Problem: npx expo start --web fails Solutions:

Install web dependencies:

npx expo install react-dom react-native-web

Check port:

# Kill process on port 19006
lsof -ti:19006 | xargs kill -9

Clear webpack cache:

rm -rf .expo .webpack
npx expo start --web --clear

CSS Not Loading on Web

Problem: Styles not applied on web Solutions:

Check Metro config:

// metro.config.js should support CSS
const config = getDefaultConfig(__dirname);
// Expo's default config includes CSS support

Import CSS:
```
import './styles.css';
```
Check CSS syntax:
- Standard CSS only
- No SCSS/SASS without configuration

Debugging Tools

Enable Debug Logging

# Expo debug mode
EXPO_DEBUG=1 npx expo start

# Metro debug mode
DEBUG=metro:* npx expo start

# React Native debug mode
REACT_DEBUGGER="open -g 'rndebugger://set-debugger-loc?port=8081' ||" npx expo start

View Bundle Size

# Generate source map
npx expo export --dump-sourcemap

# Analyze with source-map-explorer
npm install -g source-map-explorer
source-map-explorer dist/bundles/*.map

Check Native Logs

iOS:

# Simulator logs
xcrun simctl spawn booted log stream --level debug

# Device logs
idevicesyslog

Android:

# All logs
adb logcat

# Filtered logs
adb logcat | grep -i "expo"

# Clear logs
adb logcat -c

Getting More Help

If these solutions don’t work:

Search existing issues:
- GitHub Issues
- Expo Forums
Ask for help:
- Discord
- Stack Overflow
Report bugs:
- Create detailed issue on GitHub
- Include logs and reproduction steps

API Reference

Tools

Resources

Troubleshooting

Installation Issues

npm/yarn Installation Fails

Expo CLI Not Found

Metro Bundler Issues

Metro Won’t Start

Module Resolution Errors

Slow Bundle Performance

Build Errors

Native Module Linking Issues

iOS Build Failures

Android Build Failures

Runtime Errors

White Screen on Launch

App Crashes on Device

Network Request Failures

Development Build Issues

Development Build Won’t Connect

EAS Build Failures

Platform-Specific Issues

iOS Simulator Issues

Android Emulator Issues

Update & Version Issues

Incompatible Package Versions

OTA Update Not Working

Web-Specific Issues

Web App Won’t Start

CSS Not Loading on Web

Debugging Tools

Enable Debug Logging

View Bundle Size

Check Native Logs

Getting More Help

API Reference

Tools

Resources

​Installation Issues

​npm/yarn Installation Fails

​Expo CLI Not Found

​Metro Bundler Issues

​Metro Won’t Start

​Module Resolution Errors

​Slow Bundle Performance

​Build Errors

​Native Module Linking Issues

​iOS Build Failures

​Android Build Failures

​Runtime Errors

​White Screen on Launch

​App Crashes on Device

​Network Request Failures

​Development Build Issues

​Development Build Won’t Connect

​EAS Build Failures

​Platform-Specific Issues

​iOS Simulator Issues

​Android Emulator Issues

​Update & Version Issues

​Incompatible Package Versions

​OTA Update Not Working

​Web-Specific Issues

​Web App Won’t Start

​CSS Not Loading on Web

​Debugging Tools

​Enable Debug Logging

​View Bundle Size

​Check Native Logs

​Getting More Help

​Related Documentation

Installation Issues

npm/yarn Installation Fails

Expo CLI Not Found

Metro Bundler Issues

Metro Won’t Start

Module Resolution Errors

Slow Bundle Performance

Build Errors

Native Module Linking Issues

iOS Build Failures

Android Build Failures

Runtime Errors

White Screen on Launch

App Crashes on Device

Network Request Failures

Development Build Issues

Development Build Won’t Connect

EAS Build Failures

Platform-Specific Issues

iOS Simulator Issues

Android Emulator Issues

Update & Version Issues

Incompatible Package Versions

OTA Update Not Working

Web-Specific Issues

Web App Won’t Start

CSS Not Loading on Web

Debugging Tools

Enable Debug Logging

View Bundle Size

Check Native Logs

Getting More Help

Related Documentation