expo-troubleshooting
Skill8 starsChanged 3 months agoMITView on GitHub
Common Expo errors: Metro cache, version mismatch, expo-doctor, Pod install, Gradle daemon, native module conflicts, EAS Build logs, dependency hoisting. Triggers on expo error, metro cache, version mismatch, expo-doctor, expo install check, pod install error, gradle error, native module not found, build failed, eas build log, dependency conflict, hermes error, hoisting.
- Deletes or force-pushes
- Installs packages
In this repository63 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ai-automationSkill
- consultingSkill
- contentSkill
- customer-successSkill
- data-analyticsSkill
- designSkill
- design-tokensSkill
- developmentSkill
- devopsSkill
- ecommerceSkill
- emailSkill
- expo-app-configSkill
- expo-config-pluginSkill
- expo-dev-clientSkill
- expo-eas-buildSkill
- expo-eas-submitSkill
- expo-eas-updateSkill
- expo-modulesSkill
- expo-notificationsSkill
- expo-orchestratorSkill
- expo-prebuildSkill
- expo-routerSkill
- financeSkill
- frontend-tasteSkill
- marketingSkill
- market-researchSkill
- mobileSkill
- pentest-adSkill
- pentest-apiSkill
- pentest-bizlogicSkill
- pentest-bugbountySkill
- pentest-cicdSkill
- pentest-cloudSkill
- pentest-credentialsSkill
- pentest-ctfSkill
- pentest-detectionSkill
- pentest-engagementSkill
- pentest-exploit-chainSkill
- pentest-forensicsSkill
- pentest-llmSkill
- pentest-malwareSkill
- pentest-mobileSkill
- pentest-opsec-evidenceSkill
- pentest-orchestratorSkill
- pentest-privescSkill
- pentest-reconSkill
- pentest-reportSkill
- pentest-socialSkill
- pentest-stigSkill
- pentest-threat-modelSkill
- pentest-webSkill
- pentest-wirelessSkill
- productivitySkill
- productSkill
- salesSkill
- security-checkSkill
- securitySkill
- seo-crawl-budgetSkill
- seoSkill
- The first 60 shown.
The file
Files
expo-troubleshooting
Common error patterns and fix recipes in Expo + React Native projects. Metro cache, version mismatch, native build errors, reading EAS Build logs, and dependency conflicts.
What It Does
- Metro bundler cache-clearing recipe
- Health check with
expo-doctorandexpo install --check - iOS Pod install errors (mismatch, cache, deployment target)
- Android Gradle daemon, cache, multiDex
- Native module conflicts and autolinking problems
- A guide to reading EAS Build logs
- Monorepo dependency hoisting problems
Quick Health Check
npx expo-doctor
npx expo install --check
npx expo install --fix # auto-fix incompatibilitiesexpo-doctor checks these areas:
- SDK version compatibility
- Package version mismatch
- Plugin configuration
- Network access
- Native file consistency
Metro Cache Problems
Symptom: "Module not found", stale JS, a new file isn't picked up.
# Quick
npx expo start --clear
# Deeper
rm -rf node_modules/.cache .expo
watchman watch-del-all
npm cache clean --force
rm -rf $TMPDIR/metro-*
rm -rf $TMPDIR/haste-map-*
# Reset
rm -rf node_modules
npm install
npx expo start --clearwatchman problem:
watchman shutdown-server
brew install --HEAD watchman # macOSVersion Mismatch
Symptom: "react-native@0.74.x is not compatible with expo@51"
npx expo install --check
# > "react-native@X.Y is incompatible. Expected: X.Y"
npx expo install --fix
# or by hand
npx expo install react-native react react-domManual inspection:
npx expo install --check --jsoniOS Pod Install Errors
Error: "CocoaPods could not find compatible versions"
cd ios
pod repo update
pod deintegrate
rm -rf Pods Podfile.lock
pod install --repo-updateError: "Deployment target ... but pod requires iOS 15.1"
app.json:
{
"expo": {
"plugins": [
["expo-build-properties", {
"ios": { "deploymentTarget": "15.1" }
}]
]
}
}npx expo prebuild --clean
cd ios && pod installError: "Use of undeclared identifier ... missing module"
The native module couldn't be autolinked:
npx expo prebuild --clean
cd ios && pod installAndroid Gradle Errors
Error: "Could not find / Duplicate class"
cd android
./gradlew --stop
./gradlew clean
rm -rf ~/.gradle/caches/build-cache-*
rm -rf .gradle build app/build
./gradlew assembleDebug --stacktraceError: "compileSdkVersion ... required X"
app.json:
{
"expo": {
"plugins": [
["expo-build-properties", {
"android": {
"compileSdkVersion": 34,
"targetSdkVersion": 34,
"buildToolsVersion": "34.0.0"
}
}]
]
}
}Gradle Daemon Memory
android/gradle.properties:
org.gradle.jvmargs=-Xmx4096m -XX:MaxMetaspaceSize=1024m
org.gradle.daemon=true
org.gradle.parallel=true
org.gradle.configureondemand=trueMultiDex
build.gradle defaultConfig:
multiDexEnabled trueNative Module Conflict
Symptom: "Native module XYZ doesn't exist"
Checklist:
- Is the module in
package.json? - Was
npx expo prebuild --cleanrun? - iOS: was
pod installrun? - Was the dev client rebuilt? (
eas build --profile development) - Is
expo-modules-autolinkingversion-compatible?
# See the autolinking list
npx expo-modules-autolinking searchHermes Problems
Symptom: "Hermes engine ... incompatible bytecode"
# Check the Hermes version
node -e "console.log(require('hermes-engine/package.json').version)"
# Clear the cache
rm -rf ios/Pods android/build
npx expo prebuild --cleanReading EAS Build Logs
# List the latest builds
eas build:list --limit 5
# Download a specific build log
eas build:view <build-id>
# Open in the browser
eas build:view <build-id> --urlLog files:
Install dependencies— npm install/yarn outputPrebuild— config plugin output (generates the native files)Install pods— iOS pod installBuild— xcodebuild / gradle outputUpload artifact— IPA/APK upload
The error is usually in the Build stage. Read the stacktrace from the bottom up.
Dependency Hoisting (Monorepo)
Symptom: "Multiple versions of react / Module 'react' not found"
# Verify hoisting
ls node_modules/react/package.json
ls apps/mobile/node_modules/react # SHOULD NOT EXIST (should be hoisted)apps/mobile/metro.config.js:
const { getDefaultConfig } = require("expo/metro-config");
const path = require("path");
const config = getDefaultConfig(__dirname);
// Watch the workspace root
config.watchFolders = [path.resolve(__dirname, "../..")];
// Only a single React copy
config.resolver.nodeModulesPaths = [
path.resolve(__dirname, "node_modules"),
path.resolve(__dirname, "../../node_modules"),
];
// Symlink support
config.resolver.unstable_enableSymlinks = true;
module.exports = config;For pnpm:
# pnpm-workspace.yaml
packages:
- 'apps/*'
- 'packages/*'.npmrc:
node-linker=hoisted
shamefully-hoist=trueCleartext Traffic (Android)
Symptom: "Cleartext HTTP traffic to ... not permitted"
{
"expo": {
"plugins": [
["expo-build-properties", {
"android": { "usesCleartextTraffic": true }
}]
]
}
}Development only. Use HTTPS in production.
EAS Build Local Test
eas build --local --profile preview --platform androidWorks locally but crashes on EAS:
- Is
.easignoreexcluding too much? (deleting only node_modules isn't enough) - Is the EAS Node version different? (
eas.jsonnodefield) - Is an EAS Secret missing?
Network/Tunnel Problems
# Tunnel if there's a LAN problem
npx expo start --tunnel
# Tunnel slow, try LAN
npx expo start --lan
# Specific port
npx expo start --port 19000Quick Error-Fix Table
| Error | Fix |
Unable to resolve module ... | npx expo start --clear |
Native module doesn't exist | npx expo prebuild --clean && pod install |
Version mismatch | npx expo install --fix |
Pod install failed | pod repo update && pod install |
Gradle daemon disappeared | ./gradlew --stop && ./gradlew clean |
Multiple versions of react | set metro.config.js hoisting |
Hermes incompatible bytecode | Clear the cache + prebuild |
Cleartext traffic | expo-build-properties plugin |
Bundle ID invalid | app.config.ts bundle discipline |
Hard Refusal
- Deploying to production while stuck in dev mode without informing the user
- A runtime patch that bypasses a certificate error (
NSAllowsArbitraryLoadsin production) - A hack that bypasses security checks (root detection, jailbreak)
- Reading another developer's EAS build log without permission
Output Format
- Error message + category (Metro / Pod / Gradle / Autolink / Hoist)
- Quick recipe (copy-paste)
- Deep recipe (if the quick one doesn't work)
- Prevention: what to do so the same thing doesn't recur
- Next step: which skill (build, prebuild, app-config)
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

