mobile-debugging

name	mobile-debugging
description	Debug React Native apps including metro bundler issues, native errors, performance problems, and crash analysis. Use when troubleshooting errors or investigating issues.
allowed-tools	Bash, Read, Grep

Mobile Debugging

Debugging guide for React Native and Expo applications.

When to Use

• App crashes or freezes
• Metro bundler errors
• Native module issues
• Performance problems
• Build failures
• Network request debugging

Common Issues & Fixes

Metro Bundler Problems

# Clear all caches
npx expo start --clear
watchman watch-del-all
rm -rf node_modules && npm install

# Reset packager cache
rm -rf /tmp/metro-*
rm -rf /tmp/haste-*

Native Module Errors

# iOS: Reset pods
cd ios && pod deintegrate && pod install && cd ..

# Android: Clean build
cd android && ./gradlew clean && cd ..

# Expo: Prebuild clean
npx expo prebuild --clean

Simulator/Emulator Issues

# iOS: Reset simulator
xcrun simctl erase all

# Android: Wipe emulator data
adb devices  # Find device ID
adb -s DEVICE_ID emu kill

Debugging Tools

React DevTools

# Install
npm install -g react-devtools

# Start
react-devtools

# In app: Shake device -> "Debug Remote JS"

Metro Logs

# View detailed logs
npx expo start --verbose

# iOS device logs
npx react-native log-ios

# Android device logs
npx react-native log-android
adb logcat

Network Debugging

// Enable network inspector
import { Platform } from 'react-native';

if (__DEV__ && Platform.OS === 'ios') {
  require('react-native').NativeModules.DevSettings.setIsDebuggingRemotely(true);
}

// Or use Flipper for advanced network inspection

Performance Debugging

Identify Slow Renders

// Add performance logging
import { useEffect, useRef } from 'react';

function useRenderTime(componentName: string) {
  const start = useRef(performance.now());

  useEffect(() => {
    const duration = performance.now() - start.current;
    if (duration > 16) {
      console.warn(`Slow render: ${componentName} took ${duration.toFixed(2)}ms`);
    }
  });
}

// Use in components
function MyComponent() {
  useRenderTime('MyComponent');
  return <View>...</View>;
}

Memory Leaks

// Check for missing cleanup
useEffect(() => {
  const subscription = someObservable.subscribe();
  const timer = setInterval(() => {}, 1000);

  // MUST clean up!
  return () => {
    subscription.unsubscribe();
    clearInterval(timer);
  };
}, []);

Error Investigation

JavaScript Errors

# Look for error in stack trace
# Check recent file changes
# Verify imports and dependencies
# Check for typos in variable names

Native Errors

# iOS: Check Xcode console
# Android: Check Android Studio Logcat
# Look for Java/Swift exceptions
# Check native module compatibility

Build Errors

# Check package versions
npx expo-doctor

# Verify node/npm versions
node --version
npm --version

# Check for conflicting dependencies
npm ls PACKAGE_NAME

Debugging Commands

# Check what's using a port
lsof -ti:8081  # Metro bundler port
lsof -ti:19000 # Expo DevTools

# Kill process on port
kill -9 $(lsof -ti:8081)

# Check device connectivity
# iOS
xcrun simctl list devices

# Android
adb devices

# Restart adb
adb kill-server
adb start-server

Debugging Checklist

When investigating issues:

1. Reproduce: Can you consistently trigger the issue?
2. Recent Changes: What was changed before it broke?
3. Error Message: Read the full error, including stack trace
4. Dependencies: Check if packages are compatible
5. Platform: Does it happen on iOS, Android, or both?
6. Environment: Dev only or production builds too?
7. Logs: Check Metro, Xcode, and Logcat for details

Common Error Patterns

• "Unable to resolve module": Check import path and file exists
• "Invariant Violation": React error, check component lifecycle
• "Network request failed": Check API URL and network connection
• "Undefined is not an object": Check for null/undefined before accessing properties
• "Maximum call stack size exceeded": Infinite loop or recursion

Resources

• React Native Debugging
• Expo Debugging
• Flipper Debugger