agentleFS
fatihkanfatihkan/badi/.claude/skills-vault/expo-troubleshooting/SKILL.md

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

The file

Files
SKILL.md

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-doctor and expo 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 incompatibilities

expo-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 --clear

watchman problem:

watchman shutdown-server
brew install --HEAD watchman    # macOS

Version 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-dom

Manual inspection:

npx expo install --check --json

iOS 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-update

Error: "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 install

Error: "Use of undeclared identifier ... missing module"

The native module couldn't be autolinked:

npx expo prebuild --clean
cd ios && pod install

Android 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 --stacktrace

Error: "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=true

MultiDex

build.gradle defaultConfig:

multiDexEnabled true

Native Module Conflict

Symptom: "Native module XYZ doesn't exist"

Checklist:

  1. Is the module in package.json?
  2. Was npx expo prebuild --clean run?
  3. iOS: was pod install run?
  4. Was the dev client rebuilt? (eas build --profile development)
  5. Is expo-modules-autolinking version-compatible?
# See the autolinking list
npx expo-modules-autolinking search

Hermes 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 --clean

Reading 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> --url

Log files:

  • Install dependencies — npm install/yarn output
  • Prebuild — config plugin output (generates the native files)
  • Install pods — iOS pod install
  • Build — xcodebuild / gradle output
  • Upload 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=true

Cleartext 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 android

Works locally but crashes on EAS:

  • Is .easignore excluding too much? (deleting only node_modules isn't enough)
  • Is the EAS Node version different? (eas.json node field)
  • 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 19000

Quick Error-Fix Table

ErrorFix
Unable to resolve module ...npx expo start --clear
Native module doesn't existnpx expo prebuild --clean && pod install
Version mismatchnpx expo install --fix
Pod install failedpod repo update && pod install
Gradle daemon disappeared./gradlew --stop && ./gradlew clean
Multiple versions of reactset metro.config.js hoisting
Hermes incompatible bytecodeClear the cache + prebuild
Cleartext trafficexpo-build-properties plugin
Bundle ID invalidapp.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 (NSAllowsArbitraryLoads in production)
  • A hack that bypasses security checks (root detection, jailbreak)
  • Reading another developer's EAS build log without permission

Output Format

  1. Error message + category (Metro / Pod / Gradle / Autolink / Hoist)
  2. Quick recipe (copy-paste)
  3. Deep recipe (if the quick one doesn't work)
  4. Prevention: what to do so the same thing doesn't recur
  5. Next step: which skill (build, prebuild, app-config)

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.