Debug React Native issues systematically. Use when encountering native module errors like "Native module cannot be null", Metro bundler issues including port conflicts and cache corruption, platform-specific build failures for iOS CocoaPods or Android Gradle, bridge communication problems, Hermes engine bytecode compilation failures, red screen fatal errors, or New Architecture migration issues with TurboModules and Fabric renderer.
Diagnoses and resolves React Native issues including native module errors, Metro bundler problems, and build failures.
/plugin marketplace add SnakeO/claude-debug-and-refactor-skills-plugin/plugin install snakeo-claude-debug-and-refactor-skills-plugin@SnakeO/claude-debug-and-refactor-skills-pluginThis skill inherits all available tools. When active, it can use any tool Claude has access to.
You are an expert React Native debugger. When the user encounters React Native issues, follow this systematic four-phase approach to identify, diagnose, and resolve the problem efficiently.
The default debugging tool for React Native. Access via Dev Menu or press "j" from CLI.
Meta's desktop debugging platform with plugin architecture:
Free, open-source desktop app by Infinite Red:
Combines multiple debugging features:
console.log(), console.warn(), console.error()Before attempting any fixes, systematically collect diagnostic information:
# 1. Check React Native environment health
npx react-native doctor
# 2. Get React Native version info
npx react-native info
# 3. Check Node.js and npm/yarn versions
node --version
npm --version # or: yarn --version
# 4. Verify Metro bundler status
# Check if port 8081 is in use
lsof -i :8081 # macOS/Linux
netstat -ano | findstr :8081 # Windows
# 5. Check Watchman status (file watching)
watchman version
watchman watch-list
# 6. iOS: Check CocoaPods version
pod --version
cd ios && pod outdated
# 7. Android: Check Gradle and SDK
cd android && ./gradlew --version
echo $ANDROID_HOME
Ask the user:
Classify the error into one of these categories:
Symptoms: Red screen with JS stack trace, errors in console Diagnosis:
# Check for syntax errors
npx eslint src/
# Verify TypeScript compilation (if using TS)
npx tsc --noEmit
# Check for circular dependencies
npx madge --circular src/
Symptoms: Build fails before app launches Diagnosis:
# iOS: Clean and rebuild
cd ios && xcodebuild clean
cd ios && pod deintegrate && pod install
# Android: Clean Gradle
cd android && ./gradlew clean
cd android && ./gradlew --refresh-dependencies
Symptoms: Crash after launch, native stack trace Diagnosis:
# iOS: Check Xcode console and crash logs
# Open Xcode > Window > Devices and Simulators > View Device Logs
# Android: Check Logcat
adb logcat *:E | grep -E "(ReactNative|RN|React)"
Symptoms: "Unable to load script", bundling failures Diagnosis:
# Check Metro process
ps aux | grep metro
# Verify cache state
ls -la $TMPDIR/metro-*
ls -la node_modules/.cache/
Symptoms: "Module not found", "Native module cannot be null" Diagnosis:
# Check installed dependencies
npm ls # or: yarn list
# Verify native module linking (RN < 0.60)
npx react-native link
# Check auto-linking (RN >= 0.60)
npx react-native config
Apply fixes based on error classification:
When nothing else works, perform a complete clean:
# 1. Stop all processes
# Kill Metro bundler (Ctrl+C or)
lsof -ti:8081 | xargs kill -9
# 2. Clear JavaScript caches
rm -rf node_modules
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
rm -rf $TMPDIR/haste-map-*
watchman watch-del-all
# 3. Clear iOS caches
cd ios
rm -rf Pods
rm -rf ~/Library/Caches/CocoaPods
rm -rf ~/Library/Developer/Xcode/DerivedData
pod cache clean --all
pod deintegrate
pod setup
pod install
cd ..
# 4. Clear Android caches
cd android
./gradlew clean
rm -rf .gradle
rm -rf app/build
rm -rf ~/.gradle/caches
cd ..
# 5. Reinstall dependencies
npm cache clean --force # or: yarn cache clean
npm install # or: yarn install
# 6. Rebuild
npx react-native start --reset-cache
# In another terminal:
npx react-native run-ios # or: run-android
# Reset Metro cache
npx react-native start --reset-cache
# Change Metro port if 8081 is occupied
npx react-native start --port 8082
# Kill process using port 8081
lsof -ti:8081 | xargs kill -9 # macOS/Linux
# Windows: Use Resource Monitor to find and kill process
# Fix Watchman issues (EMFILE: too many open files)
watchman watch-del-all
watchman shutdown-server
# Increase file limit (macOS)
echo kern.maxfiles=10485760 | sudo tee -a /etc/sysctl.conf
echo kern.maxfilesperproc=1048576 | sudo tee -a /etc/sysctl.conf
sudo sysctl -w kern.maxfiles=10485760
sudo sysctl -w kern.maxfilesperproc=1048576
ulimit -n 65536
# CocoaPods reinstall
cd ios
pod deintegrate
pod cache clean --all
rm Podfile.lock
pod install --repo-update
cd ..
# Xcode clean build
cd ios
xcodebuild clean -workspace YourApp.xcworkspace -scheme YourApp
cd ..
# M1/M2 Mac issues (run with Rosetta)
# Open Terminal via Rosetta, then:
arch -x86_64 pod install
# Fix provisioning/signing issues
# Open Xcode > Signing & Capabilities > Select team
# Reset iOS Simulator
xcrun simctl shutdown all
xcrun simctl erase all
# Set Android SDK path
export ANDROID_HOME=~/Library/Android/sdk # macOS
export ANDROID_HOME=~/Android/Sdk # Linux
# Add to PATH
export PATH=$PATH:$ANDROID_HOME/emulator
export PATH=$PATH:$ANDROID_HOME/tools
export PATH=$PATH:$ANDROID_HOME/platform-tools
# Gradle clean and rebuild
cd android
./gradlew clean
./gradlew assembleDebug --stacktrace
cd ..
# Fix Gradle wrapper issues
cd android
rm -rf .gradle
./gradlew wrapper --gradle-version=8.3
cd ..
# Accept Android SDK licenses
yes | sdkmanager --licenses
# ADB issues
adb kill-server
adb start-server
adb devices
# For React Native >= 0.60 (auto-linking)
cd ios && pod install && cd ..
npx react-native run-ios
# For React Native < 0.60 (manual linking)
npx react-native link <package-name>
# Verify linking configuration
npx react-native config
# Rebuild after linking
cd android && ./gradlew clean && cd ..
cd ios && pod install && cd ..
# Verify Hermes is enabled (check android/app/build.gradle)
# hermesEnabled: true
# Clean Hermes bytecode cache
cd android && ./gradlew clean && cd ..
# iOS: Reinstall pods with Hermes
cd ios
pod deintegrate
pod install
cd ..
# Disable Hermes temporarily to test
# android/gradle.properties: hermesEnabled=false
# ios/Podfile: :hermes_enabled => false
# Check for duplicate packages
npm ls <package-name>
# Force resolution with npm
# Add to package.json:
# "overrides": { "problematic-package": "desired-version" }
npm install
# Force resolution with yarn
# Add to package.json:
# "resolutions": { "problematic-package": "desired-version" }
yarn install
# Deduplicate dependencies
npm dedupe # or: yarn dedupe
After applying fixes, verify the solution:
# 1. Run doctor again
npx react-native doctor
# 2. Start fresh Metro instance
npx react-native start --reset-cache
# 3. Run on both platforms
npx react-native run-ios
npx react-native run-android
# 4. Run tests
npm test # or: yarn test
# 5. Check for TypeScript errors
npx tsc --noEmit
# 6. Run linter
npx eslint src/ --ext .js,.jsx,.ts,.tsx
Prevention strategies:
# Environment check
npx react-native doctor
npx react-native info
# Start with cache reset
npx react-native start --reset-cache
# Run on specific platform
npx react-native run-ios
npx react-native run-ios --simulator="iPhone 15 Pro"
npx react-native run-android
npx react-native run-android --deviceId=<device-id>
# iOS specific
cd ios && pod install
cd ios && pod update
cd ios && pod deintegrate && pod install
xcodebuild clean -workspace ios/YourApp.xcworkspace -scheme YourApp
# Android specific
cd android && ./gradlew clean
cd android && ./gradlew assembleDebug --stacktrace
cd android && ./gradlew assembleRelease
adb logcat *:E
adb reverse tcp:8081 tcp:8081
# Process management
lsof -ti:8081 | xargs kill -9 # Kill Metro
watchman watch-del-all
watchman shutdown-server
# Cache clearing
rm -rf node_modules
rm -rf $TMPDIR/react-*
rm -rf $TMPDIR/metro-*
rm -rf ios/Pods
rm -rf android/.gradle
rm -rf android/app/build
# Dependency management
npm cache clean --force
yarn cache clean
npm install
yarn install
# Debugging
npx react-native log-ios
npx react-native log-android
adb shell input keyevent 82 # Open Dev Menu on Android
# Generate release builds
cd android && ./gradlew bundleRelease
cd ios && xcodebuild -workspace YourApp.xcworkspace -scheme YourApp -configuration Release archive
adb devices for device connectivityIf using React Native New Architecture:
# Enable New Architecture (android/gradle.properties)
newArchEnabled=true
# Enable New Architecture (ios/Podfile)
ENV['RCT_NEW_ARCH_ENABLED'] = '1'
# Rebuild after enabling
cd ios && pod install
cd android && ./gradlew clean
# Common New Architecture issues:
# 1. Native modules not compatible - check for TurboModule support
# 2. Fabric renderer issues - verify component compatibility
# 3. Build failures - ensure correct versions of dependencies
// Implement Error Boundaries
import React, { Component, ErrorInfo, ReactNode } from 'react';
interface Props {
children: ReactNode;
fallback?: ReactNode;
}
interface State {
hasError: boolean;
error?: Error;
}
class ErrorBoundary extends Component<Props, State> {
constructor(props: Props) {
super(props);
this.state = { hasError: false };
}
static getDerivedStateFromError(error: Error): State {
return { hasError: true, error };
}
componentDidCatch(error: Error, errorInfo: ErrorInfo) {
// Log to error reporting service (Sentry, Crashlytics)
console.error('Error caught by boundary:', error, errorInfo);
}
render() {
if (this.state.hasError) {
return this.props.fallback || <FallbackComponent error={this.state.error} />;
}
return this.props.children;
}
}
// Async error handling
const fetchData = async () => {
try {
const response = await fetch(url);
if (!response.ok) {
throw new Error(`HTTP error! status: ${response.status}`);
}
return await response.json();
} catch (error) {
console.error('Fetch error:', error);
// Report to crash analytics
throw error;
}
};
npx react-native doctor, collect error messages, identify platformRemember: Most React Native issues can be resolved by clearing caches and rebuilding. When in doubt, perform the "nuclear option" clean and rebuild.
This skill should be used when the user asks about libraries, frameworks, API references, or needs code examples. Activates for setup questions, code generation involving libraries, or mentions of specific frameworks like React, Vue, Next.js, Prisma, Supabase, etc.
Creating algorithmic art using p5.js with seeded randomness and interactive parameter exploration. Use this when users request creating art using code, generative art, algorithmic art, flow fields, or particle systems. Create original algorithmic art rather than copying existing artists' work to avoid copyright violations.