What this usually means
EAS Build failures are almost never random. They usually fall into one of three categories: (1) a mismatch between local and EAS environments (e.g., different Node versions, missing environment variables), (2) native module configuration issues (e.g., auto-linking failed, wrong native dependency version), or (3) credential/profile problems for iOS builds. The EAS build logs are your primary tool, but they can be verbose and hide the needle. Understanding the build phases (install, prebuild, build) helps narrow down where the error occurs.
The first ten minutes — establish facts before touching code.
- 1Run `eas build:version` to check your EAS CLI version; update if outdated (`npm install -g eas-cli`).
- 2Check the build logs on Expo's dashboard: navigate to the failed build, click 'View logs', and search for 'FAILURE' or 'error'.
- 3If the build fails early, look at the 'Install' phase logs for dependency resolution errors (e.g., `npm ERR!` or `yarn error`).
- 4If it fails during 'Build', look for 'Gradle' or 'Xcode' errors specific to native code (e.g., 'Task :app:compileDebugKotlin FAILED').
- 5Run `npx expo doctor` to detect common misconfigurations in your project (e.g., incompatible packages, missing fields in app.json).
- 6Test your build locally with `expo run:android` or `expo run:ios` to see if the issue reproduces outside EAS.
The specific files, logs, configs, and dashboards that usually own this bug.
- searchExpo dashboard build logs: https://expo.dev/accounts/<account>/projects/<project>/builds/<build-id>
- searchLocal terminal output from `eas build --platform android --local` (or ios) to see if it fails identically
- search`expo-updates` configuration in app.json or app.config.js (typos cause cryptic errors)
- search`android/app/build.gradle` and `ios/Podfile` if you have custom native code
- searchCredentials store in EAS: `eas credentials` to verify provisioning profiles and push keys
- searchEnvironment variables set in EAS Build profiles (check if missing variables cause build-time errors)
Practical causes, not theory. These are the things you will actually find.
- warningMissing or incorrect iOS distribution certificate or provisioning profile in EAS credentials
- warningOutdated EAS CLI version that doesn't match the EAS Build server's expected format
- warningIncompatible native module version — e.g., using a module that requires a higher minSdkVersion
- warningEnvironment variables required at build time (like API keys) are not set in the EAS Build profile
- warning`expo-updates` misconfigured causing build-time schema validation errors
- warningNode.js version mismatch: EAS uses Node 16 by default, but your project requires 18+
Concrete fix directions. Pick the one that matches your root cause.
- buildUpdate EAS CLI: `npm install -g eas-cli@latest` and clear cache: `eas build:clear-cache`
- buildRun `expo prebuild --clean` locally to regenerate native folders, then commit and try again
- buildFor iOS credential issues: `eas credentials --platform ios` to manage certificates and profiles
- buildFor Android: ensure `android/gradle.properties` has correct memory settings (e.g., `org.gradle.jvmargs=-Xmx4g`)
- buildSet environment variables in `eas.json` under `build.<profile>.env` explicitly
- buildPin Node version in `eas.json` using `node` field in the build profile, e.g., `"node": "18.17.0"`
A fix you cannot prove is a guess. Close the loop.
- verifiedRun the same build again with `eas build --platform android --profile staging` and confirm it completes
- verifiedTest a simple Hello World Expo app with the same EAS profile to isolate whether the issue is project-specific
- verifiedCompare successful build logs from a previous working commit with the failing logs
- verifiedRun `expo doctor` again after fixes to ensure no new warnings
- verifiedDeploy to TestFlight or internal distribution to verify the build actually runs on device
Things that make this bug worse or harder to find.
- warningDon't blindly re-run `eas build` without reading the full log — the error is usually near the bottom but sometimes hidden in the middle
- warningDon't assume that because it works locally with `expo start` it will work on EAS — local development uses Metro bundler, EAS uses a full native build
- warningAvoid adding native modules without running `expo install` (which picks compatible versions) — use `npx expo install` instead of npm/yarn
- warningDon't ignore warnings in the build log — sometimes a warning like 'SDK version mismatch' precedes the failure
- warningNever commit generated `android` and `ios` folders unless you understand the implications — let EAS generate them via `expo prebuild`
EAS Build Failed After Adding react-native-maps
Timeline
- 09:00Added react-native-maps via `npx expo install react-native-maps`
- 09:15Ran `eas build --platform ios --profile preview`
- 09:18Build failed after 2 minutes with 'Xcode build failed' — no clear error
- 09:20Scrolled logs: found 'error: Build input file cannot be found: .../AirMaps.xcodeproj'
- 09:25Checked Podfile: react-native-maps was not listed under `use_frameworks!`
- 09:30Ran `expo prebuild --clean` to regenerate ios folder
- 09:35Re-ran `eas build --platform ios --profile preview`
- 09:40Build succeeded. Artifact available for download.
I had been working on a feature that required maps, so I added react-native-maps using `npx expo install` as recommended. The install succeeded, and the app ran fine on my simulator with `expo run:ios`. Confident, I triggered an EAS Build for internal distribution. The build failed with a generic 'Xcode build failed' message. The error log was hundreds of lines long, and I nearly missed the real issue.
Scrolling through the logs, I noticed a line about missing build input file for AirMaps.xcodeproj. That's a native module that ships with react-native-maps. The problem was that EAS Build uses Expo's auto-linking, but the ios folder hadn't been regenerated after adding the module. My local ios folder was stale, and EAS was using that cached version. Running `expo prebuild --clean` regenerated the native project with the proper references.
The lesson: always regenerate native folders when adding or removing native modules, even if it works locally. The local development server can sometimes mask missing native references because it uses a different build pipeline. I now make it a habit to run `expo prebuild --clean` and commit the resulting changes before triggering any EAS Build.
Root cause
Stale native ios folder — react-native-maps added but `expo prebuild` not run, so the Podfile and xcodeproj were missing references to the AirMaps library.
The fix
Run `expo prebuild --clean` to regenerate the ios and android folders, then commit and rebuild on EAS.
The lesson
Always run `expo prebuild --clean` after changing native dependencies, even if it works locally. EAS uses the local native folders for the build.
EAS Build runs in three sequential phases: Install, Prebuild, Build. Each phase has its own log section. The Install phase resolves npm/yarn dependencies. If you see an error here, it's usually a version conflict or network issue. The Prebuild phase runs `expo prebuild` to generate native projects if needed. Errors here often indicate missing or incompatible native modules. The Build phase compiles the native code with Gradle (Android) or Xcode (iOS). Failures here are typically due to native code issues, like missing libraries or misconfigured build settings.
When diagnosing, first identify which phase fails. The log header clearly marks each phase. Jump to the end of the failing phase and look for the first 'error' or 'FAILURE' line. Don't read the entire log from top to bottom — that's a waste of time. Use the search function in the browser to find 'error:' or 'FAILURE'.
iOS builds require valid Apple Developer credentials: a distribution certificate and a provisioning profile. EAS manages these via `eas credentials`. A common failure is when the certificate expires or the provisioning profile doesn't include the device's UDID. The error message might be 'No matching provisioning profile found' or 'Code signing failed'.
To fix, run `eas credentials --platform ios` and follow the interactive prompts to revoke and regenerate credentials. Alternatively, you can manually upload a certificate and profile. Always ensure your Apple Developer account has the correct bundle ID and that the profile includes the devices you're testing on. For distribution, use an App Store or Ad Hoc profile accordingly.
Many apps require environment variables at build time, such as API keys or configuration toggles. EAS Build does not automatically inherit your local `.env` file. You must explicitly define variables in the build profile under `env` in `eas.json`. If a variable is missing, the build might compile but crash at runtime, or worse, fail at build time if the code uses the variable in a conditional that causes a syntax error.
A pattern I've seen: developers set `EXPO_PUBLIC_API_URL` in their local `.env` but forget to add it to `eas.json`. The build succeeds, but the app uses `undefined` for the URL. To avoid this, use `expo-constants` to read environment variables at runtime and fail fast if they're missing. Also, consider using EAS Secrets for sensitive values: `eas secret:create`.
EAS Build caches dependencies to speed up subsequent builds. However, this cache can become stale, causing builds to fail after dependency changes. If you suspect caching, add `--clear-cache` to your build command: `eas build --platform android --clear-cache`. Alternatively, you can clear the cache in the EAS dashboard under the project settings.
Another caching issue is with Metro bundler. EAS uses Metro to bundle JavaScript, and it caches the bundle. If you've changed native code, the cached bundle might be incompatible. Running `expo start -c` locally clears Metro cache, but for EAS, the `--clear-cache` flag also clears Metro's cache. I always use `--clear-cache` when I've changed native dependencies or configurations.
Frequently asked questions
Why does my build fail only on EAS but not locally?
Local development uses Expo's development build, which compiles on the fly and may not reflect all native code issues. EAS Build runs a full native build (Gradle/Xcode) with production settings. Differences in Node version, environment variables, or native folder state can cause failures on EAS that don't appear locally. Always run `expo run:android` or `expo run:ios` after `expo prebuild` to approximate the EAS environment.
How do I find the exact error in the EAS build logs?
Open the build log in the Expo dashboard and use the browser's search (Ctrl+F or Cmd+F) for 'error:', 'FAILURE', or 'Exited with code'. The actual error is often at the end of the failing phase. For Gradle builds, search for 'BUILD FAILED'. For Xcode, search for 'error:'. Ignore warnings and informational messages.
What is the most common cause of EAS Build failures?
In my experience, the most common cause is a stale native folder — the `ios` or `android` directory not being regenerated after adding/removing native modules. The fix is to run `expo prebuild --clean` and commit the changes. Second most common is iOS credential issues, especially when certificates expire.
Can I debug an EAS Build locally before pushing?
Yes, use `eas build --platform android --local` (or `--platform ios --local`) to run the build on your machine. This uses the same build scripts as the cloud but runs locally. It's slower but gives you direct access to logs and allows you to inspect intermediate files. Note that local builds require Xcode or Android Studio installed.
What should I do if the build fails with 'unable to load script'?
This usually means the JavaScript bundle failed to build. Check the 'Bundle JS' phase in the logs. Common causes: syntax error in your code, missing module, or Metro bundler running out of memory. Try `expo export --platform android` (or ios) locally to see if the bundle compiles. Increase Metro's memory limit by setting `--max-workers=2` or adding `process.env.METRO_MAX_WORKERS = 2` to metro.config.js.