A reference for troubleshooting build errors and crashes when using EAS Build.
This document is under active development; the topic it covers is expansive and finding the right way to explain how to troubleshoot issues will take some trial and error. Your suggestions for improvements are welcome as pull requests.
When something goes wrong, it probably will go wrong in one of two following ways:
All standard advice around narrowing down the source of an error applies here; this document provides information that may be useful on top of your typical troubleshooting processes and techniques. Troubleshooting is an art, and you might need to think creatively.
Before you go further, you need to be sure that you have located the error message and read it. How you do this will be different depending on whether you're investigating a build failure or runtime error.
Common questions that fall under this category are: "my app runs well locally by crashes immediately when I run a build" or "my app works in Expo Go but hangs on the splash screen in my build". When your app builds successfully but crashes or hangs when you run it, this is considered a runtime error.
Refer to the "Production errors" section of the debugging guide to learn how to locate logs when your release builds are crashing at runtime.
If can't find any useful information through this approch, try narrowing down the source of the crash step by step.
Go to your build details page (find it on the build dashboard if you don't have it open already) and expand any failed build phases by clicking on them. Often, the earliest phase with errors will contain the most useful information and any subsequent failed phase will have cascaded from the first.
Regardless of the phase, it's common to see log entries prefixed with
[stderr], but keep in mind that this doesn't necessarily mean those logs point to errors; it's common for CLI tools to use stderr to output warnings and other diagnostics.
For example, you might see something like this on your Android builds:
[stderr] Note: /build/workingdir/build/app/node_modules/@react-native-async-storage/async-storage/android/src/main/java/com/reactnativecommunity/asyncstorage/AsyncStorageModule.java uses or overrides a deprecated API.
[stderr] Note: Recompile with -Xlint:deprecation for details.
❌ Metro encountered an error:
Unable to resolve module ./src/Routes from /Users/expo/workingdir/build/App.js
This particular error means that the app is importing ./src/Routes and it is not found. The cause could be that the filename case is different in Git than the developer's filesystem (for example, routes.js in Git instead of Routes.js), or maybe the project has a build step and it wasn't set up to run on EAS Build. In this case, it turns out that in this case ./src/Routes was intended to import ./src/Routes/index.js, but that path was accidentally excluded in the developer's .gitignore.
It's important to note that with iOS builds the build details page only displays an abridged version of the logs because the full output from
npx expo-doctor to determine that the versions of Expo SDK dependencies in your project are compatible with your Expo SDK version.
Armed with your error logs, you can often start to fix your build or search the forums and GitHub issues for related packages to dig deeper. Some common sources of problems are listed below.
Monorepos are incredibly useful but they do introduce their own set of problems. It's necessary to upload the entire monorepo to the EAS Build builders, set it up, and run the build.
For more information, see Working with monorepos.
To determine how large your bundle is and to see a breakdown of where the size comes from, use react-native-bundle-visualizer.
When a build fails with
Task :app:bundleReleaseJsAndAssets FAILED (Android) or
You can build the production bundle locally by running
npx expo export to bypass all of the other build steps so you can see this error much more quickly. Run this command repeatedly, resolving any syntax errors or other issues uncovered until the bundle builds successfully. Then try your EAS Build again.
If the logs weren't enough to immediately help you understand and fix the root cause, it's time to try to reproduce the issue locally. If your project builds and runs locally in release mode then it will also build on EAS Build, provided that the following are all true:
You can verify that your project builds on your local machine with the
npx expo run:android and
npx expo run:ios commands, with variant/configuration flags set to release to most faithfully reproduce what executes on EAS Build. For more information, see Android build process and iOS build process.
# Locally compile and run the Android app in release mode
npx expo run:android --variant release
# Locally compile and run the iOS app in release mode
npx expo run:ios --configuration Release
If use CNG, these commands will run
npx expo prebuildto generate native projects to compile them.You likely want to clean up the changes once you are done troubleshooting, unless you want to start managing these projects directly instead of generating them on demand.
You can alternatively run a local build with
eas build --local— this command will run a series of steps that is as close as it can be to what runs remotely on the hosted EAS Build service. It will copy your project to a temporary directory and make any necessary changes there. Learn how to set this up and use it for debugging.
If your native toolchains are installed correctly and you are unable to build and run your project in release mode on your local machine, it will not build on EAS Build. Fix the issues locally, then try again on EAS Build. The other advice in this doc may be useful to help you resolve the issue locally, but often this requires some knowledge of native tooling or judicious application of Google, Stack Overflow, and GitHub Issues.
If you do not have native toolchains installed locally, for example, because you do not have an Apple computer and therefore cannot build an iOS app on your machine, it can be trickier to get to the bottom of build errors. The feedback loop of making small changes locally and then seeing the result on EAS Build is slower than doing the same steps locally because the EAS Build builder must set up its environment, download your project, and install dependencies before starting the build.
If you are willing and able to set up the appropriate native tools, then refer to the React Native environment setup guide.
By default, EAS Build follows a relatively straightforward process for building your app for (Android or iOS). If
npx expo run:android --variant release and
npx expo run:ios --configuration Release work locally, but your builds fail, then it's time to narrow down what configuration exists on your machine that hasn't been set up for your project on EAS Build yet.
git cloneof your project to a new directory and get it running, ideally on a different machine. Pay attention to each of the steps that are needed and verify that they are also configured for EAS Build.
You can test how the JS part of your app will run in production by starting it with
__DEV__ boolean. This will remove most of the logging, HMR, Fast Refresh functionality, and make debugging a bit harder, but you can iterate on the production bundle faster this way.
This guide is far from being comprehensive, and depending on your level of experience you might still be struggling to get your app working.
If you have followed the advice here, you're now in a good position to describe your issue to other developers and get some help.
Join us on Discord and Forums to ask for help from the community and the Expo team. The Expo team does our best to respond to high quality and well-articulated questions and issues, but responses are not guaranteed unless you are signed up for a support plan. To ensure that an Expo team member sees your question, you can file a ticket at expo.dev/contact.
When you ask for troubleshooting help, be sure to share the following information:
eas build --local, you may omit this, but please indicate this fact.
Try to be clear, precise, and helpful. General guidance provided by Stack Overflow's How to ask a good question guide applies.