React Native: Unable to load script. Make sure you're running Metro

Quick fix

Read the commands before running them. Anything that restarts a service, deletes data or changes permissions should be tried on a non-production system first.

# Metro has to be running, on the port the app expects
npx react-native start --port 8081

# Physical Android device: forward the port to the phone
adb reverse tcp:8081 tcp:8081
adb devices          # the device must be listed as "device", not "unauthorized"

# Emulator uses 10.0.2.2 for the host; Genymotion uses 10.0.3.2
# Shake the device -> Dev Settings -> Debug server host: 192.168.1.20:8081

# Stale cache after a dependency change
watchman watch-del-all
npx react-native start --reset-cache

# Release build with no bundle: generate it
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

How to diagnose Mobile errors

Mobile build errors are overwhelmingly toolchain and dependency version conflicts rather than code problems. Android builds fail on Gradle, JDK and Android Gradle Plugin version combinations; iOS builds fail on code signing, provisioning profiles and CocoaPods lockfile drift. The productive instinct is to check version compatibility matrices before reading stack traces.

If the quick fix above does not resolve it, work through these steps. They apply to this whole class of error, not just to this one message, which is usually what saves the time.

1. Run the build with full output: ./gradlew assembleDebug --stacktrace --info. Gradle's default output hides the actual failing task.
2. Verify the JDK the build is using (./gradlew -version), not the one on your PATH. Android Gradle Plugin has strict JDK requirements.
3. For CocoaPods, run pod install, not pod update, after pulling changes, and open the .xcworkspace rather than the .xcodeproj.
4. For code signing, check the provisioning profile's expiry, bundle identifier and device list in Xcode's Signing & Capabilities tab before touching certificates.
5. Clear caches only as a last resort and one at a time (./gradlew clean, rm -rf ~/Library/Developer/Xcode/DerivedData, watchman watch-del-all), so you learn which one mattered.

Tools worth reaching for

• ./gradlew --stacktrace --info
• pod install
• xcodebuild -showBuildSettings
• flutter doctor -v
• adb logcat

Authoritative references

Primary documentation for this error, worth reading before applying any fix in production.

📖 reactnative.dev

Related Mobile errors

• Android Studio: Gradle sync failedAndroid Studio cannot sync the project with Gradle files. Usually caused by SDK version…
• Android: DEX method limit exceeded (64k)The app has more than 65,536 methods across all DEX files. Android's Dalvik bytecode format…
• Android: Duplicate class found in modulesTwo dependencies bring in the same class, usually because one ships a bundled copy of a…
• Android: INSTALL_FAILED_UPDATE_INCOMPATIBLEAn app with the same package name is already installed but signed with a different key…
• Android: Manifest merger failed with multiple errors, see logsGradle merges your manifest with every library manifest, and two of them disagree: usually a…
• Android: SDK location not found. Define a valid SDK locationGradle looks for sdk.dir in local.properties, then for the ANDROID_HOME environment variable…
• CocoaPods: The sandbox is not in sync with the Podfile.lockInstalled pods don't match the manifest lockfile. Common after switching git branches.
• Expo EAS: build failed (Gradle/Xcode step exited with non-zero code)EAS Build failed during the native compile step. The wrapper message is generic; the real…

See all 17 Mobile errors →

Browse other categories

• HTTP 494xx client errors, 5xx server errors, redirects, headers and protocol problems.
• JavaScript 42npm resolution, async pitfalls, hydration, memory limits and runtime type…
• Database 41Connections, deadlocks, constraints, replication and memory limits.
• AI 35Rate limits, context windows, GPU memory and model-serving failures.
• Network 35Refused connections, timeouts, resets, MTU problems and port exhaustion.
• Python 35Imports, virtual environments, encoding, concurrency and dependency conflicts.
• Kubernetes 34CrashLoopBackOff, ImagePullBackOff, OOMKilled, RBAC, scheduling and storage.
• Docker 27Daemon connectivity, disk space, image pulls, ports and architecture mismatches.
• System 26Disk space, systemd units, file descriptors, OOM killer and scheduled jobs.
• Cloud 25IAM permissions, quotas, service limits and credential failures.
• Security 25JWT validation, CSRF, OAuth grants, SELinux, SSH host keys and CSP.
• TLS 24Untrusted authorities, expiry, hostname mismatch, chains and cipher negotiation.

Something missing or wrong?

This entry is maintained by hand. If the fix is out of date, incomplete, or you have a better one, email a correction and it will be reviewed.