Expo Troubleshooting with Practical Examples

Intro

Expo is a powerful open-source platform for building React Native apps with a managed workflow. It abstracts away much of the native configuration complexity, but like any toolchain, it can fail in confusing ways. When a build breaks, a dev server refuses to start, or a deployed app crashes, you need a structured approach to move from symptom to verified fix.

This guide is written for developers, DevOps engineers, and startup technical teams who use Expo in production or active development. It provides practical troubleshooting workflows that combine command-line checks, configuration validation, log analysis, and recovery procedures. Every example includes a concrete command, the expected output, and failure signals to watch for.

The underlying principle is operational safety: observe before changing, limit blast radius, use placeholders for secrets, verify results, and document how to recover if the expected state is not reached.

Version and Environment Inventory

Before you change anything, you need to know exactly what you are running. Many Expo issues are caused by version mismatches between the Expo CLI, the project's Expo SDK, React Native, and native tooling. Start by collecting the current state of your environment.

Prerequisites:

• Node.js installed (LTS recommended)
• npm or yarn package manager
• Project directory with package.json
• Access to terminal

Read-only observation commands:

Check the Expo CLI version globally and locally:

npx expo --version

Expected output example:

6.3.10

Check the project's key dependencies without modifying anything:

npm list expo react-native react

Expected output should include versions for each. If npm list reports missing or invalid packages, that is a strong signal of dependency corruption.

Check your Node.js version:

node --version

Check your npm version:

npm --version

Expo SDK 49 and later typically require Node 16 or newer. If your Node version is below the required level, many commands will fail with cryptic errors like Cannot find module 'node:path' or SyntaxError: Unexpected token '??='.

Check your git branch and recent changes to understand what might have changed:

git status

git log --oneline -5

Blast radius and recovery: Running read-only commands has no blast radius. If you discover a version mismatch, the smallest justified change is usually to align versions using the official Expo upgrade helper or by reinstalling dependencies. Before making any change, commit your current state or note it down so you can return to it.

Verification after inventory: Record the values you find. For example, you might note: "Expo CLI 6.3.10, SDK 49, React Native 0.72.6, Node v18.17.1, npm 9.6.7". This becomes your baseline for later comparison.

Safe Configuration Path

Configuration issues are frequent sources of Expo problems. The manifest file app.json or app.config.js controls how your app is built and run. A single typo or invalid field can prevent the dev server from starting or cause EAS Build to fail.

Read-only observation of your current configuration:

npx expo config --type public

This command prints the resolved public configuration. Expected output is a JSON object with keys like name, slug, version, ios, android, etc. Look for unexpected null values or missing fields.

For a more complete view including internal fields:

npx expo config --type introspect

Common configuration problems:

1. Invalid app.json: The file must be valid JSON. A trailing comma or missing brace will cause a parse error. Validate it with:

node -e "JSON.parse(require('fs').readFileSync('app.json', 'utf8')); console.log('Valid JSON')"

Expected output: Valid JSON. If you see an error, fix the JSON syntax.

1. Missing icon or splash screen: If your icon or splash paths are wrong, EAS Build may fail when generating native assets. Verify the file exists:

ls assets/icon.png assets/splash.png

If one is missing, replace it with a valid PNG file and update the path in app.json.

1. Scheme issues: If you use deep linking, the scheme field must not contain special characters. Check it with:

npx expo config --type public | grep scheme

Making a safe change to configuration:

Suppose you need to change the versionCode for Android. First, make a backup of your app.json:

cp app.json app.json.backup

Then edit the field to a new integer value.

After the change, verify the configuration still resolves:

npx expo config --type public > /dev/null && echo "Config OK"

If you get an error, revert using the backup:

cp app.json.backup app.json

Then investigate the syntax or field type.

Recovery path: Always keep the backup until you have confirmed the app works in development and, if applicable, a new build succeeds.

Verification and Diagnostics

Once you have a stable environment and configuration, you need to observe the app's behavior and diagnose issues. Expo offers several diagnostic tools.

Starting the development server with verbose logging:

npx expo start --verbose

Watch for lines indicating the server is ready, such as:

Waiting on http://localhost:8081

If you see errors like Metro bundler encountered an error, note the file path and error message.

Viewing device logs:

For Android, you can use adb (if platform tools are installed):

adb logcat -s ReactNativeJS

For iOS, use the Expo Go app's built-in log viewer or run:

npx expo start --ios

Then check the terminal for JS logs.

Running a diagnostic build:

For EAS Build, you can run a local build to isolate issues:

npx eas build --platform android --profile preview --local

This runs the build on your machine, giving you direct access to logs. Expected output includes progress on each step: installing dependencies, running prebuild, compiling native code, and producing an artifact.

Checking dependency health:

npx expo-doctor

This command checks for common issues like incompatible versions or missing configuration. Expected output is a list of checks, each with a pass or fail status. For example:

✔ Check Expo config (app.json/ app.config.js)
✔ Check package.json
✔ Check dependencies for compatibility

If any check fails, it will list the problem and often suggest a fix.

Interpreting failure signals:

• "Unable to resolve module" means a dependency is missing or incorrectly referenced. Check your imports and package.json.
• "Invariant Violation: Native module cannot be null" often means a native module is not linked correctly. In Expo Go, some modules are unsupported; you may need a development build.
• Bundling errors that mention a specific file indicate a syntax error or unsupported language feature.

Verification step after any fix: After making a change, clear the Metro bundler cache and restart:

npx expo start --clear

Then reload the app and check if the error is gone.

Failure Modes and Recovery

Understanding common failure modes and having a recovery plan is critical. Here are some frequent issues and how to recover.

1. Dependency version mismatch

Symptom: You see errors like TypeError: Cannot read property 'foo' of undefined or The native module X doesn't exist after updating packages.

Why it happens: You upgraded one package but not others, or you have a mix of Expo SDK versions.

Recovery:

npx expo install --fix

This command attempts to align dependencies with the installed Expo SDK. If that fails, manually edit package.json to use the versions recommended by npx expo install for each package, then run:

npm install

and clear cache:

npx expo start --clear

2. Metro bundler cache corruption

Symptom: The dev server does not pick up changes, or you see stale errors even after fixing code.

Why it happens: The Metro cache can become inconsistent.

Recovery:

npx expo start --clear

If that does not work, delete the cache directories manually:

rm -rf node_modules/.cache .expo

Then reinstall and restart:

npm install
npx expo start

3. EAS Build configuration error

Symptom: eas build fails with a message about eas.json or missing credentials.

Why it happens: eas.json may have invalid profiles or missing fields.

Recovery: Validate eas.json with:

npx eas build:inspect

This shows what would be built. Fix any errors in eas.json, then re-run the build.

4. Port 8081 already in use

Symptom: npx expo start fails with Error: listen EADDRINUSE: address already in use :::8081.

Why it happens: Another process occupies the port.

Recovery: Find the process and kill it (on Linux/macOS):

lsof -ti tcp:8081 | xargs kill

On Windows, use:

netstat -ano | findstr :8081

then taskkill /PID <PID> /F. Alternatively, start Expo on a different port:

npx expo start --port 8082

5. App crashes on device after update

Symptom: The app works in development but crashes in production after a new OTA update or build.

Why it happens: New native modules were added but the updated binary was not rebuilt, or OTA update contains JS incompatible with the binary.

Recovery: Revert the OTA update if possible. For EAS Update, you can republish a previous commit. For native changes, create a new build with eas build. In development, test with a development build rather than Expo Go if you use custom native code.

Common Pitfalls

Avoid these frequent mistakes when troubleshooting Expo.

1. Ignoring environment differences: What works on one developer's machine may fail on another due to Node version, global packages, or environment variables. Always run the version inventory commands before assuming a bug.

1. Modifying multiple things at once: If you change both code and configuration simultaneously, you cannot pinpoint the cause. Make one change, test, then proceed.

1. Using real secrets in test commands: When testing API calls or environmental variables, never put actual tokens or passwords in commands that might be logged or shared. Use placeholder values like YOUR_API_KEY in all examples.

1. Not checking Expo Go compatibility: Many libraries with native code do not work in Expo Go. If you see errors about native modules, switch to a development build.

1. Skipping cache clearing: Stale caches cause mysterious errors. Make --clear part of your routine when facing odd bundling issues.

Operations Checklist

Use this checklist when troubleshooting Expo. For each item, one person should be accountable for completing it, and the results should be recorded in your team's issue tracker or runbook. Review the checklist weekly for active incidents or monthly as a health check.

After completing the checklist, update the system status record with the date, observed values, and any discrepancies. If a step fails, assign the accountable owner to investigate and document the recovery steps taken.

Conclusion

Expo troubleshooting becomes manageable when you approach it systematically. Start by inventorying your environment and configuration, make small, reversible changes, verify each step with concrete commands, and know the common failure modes and their recoveries. Use the operational checklist to ensure consistency across your team.

Remember that a reliable troubleshooting workflow makes failure visible, protects sensitive values, limits changes to the intended resource, and defines recovery verification before an incident forces the decision. With the practical examples in this guide, you can resolve most Expo issues quickly and with confidence.