Troubleshooting build errors and crashes
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 ways: 1) your build will fail, or 2) the build will succeed but encounter a runtime error, eg: it crashes or hangs when you run it.
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.
Refer to the debugging guide
to learn how to locate logs when your release builds are crashing at runtime.
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.
While you may or may not be interested in following up on that warning, it is not the cause of your failed build. So how do you know which logs are truly responsible? If you are building a bare project, you will already be good at this. If you are building a managed project
❌ 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 being different in Git than the developer's filesystem (eg:
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
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
or a dependency in your project. Keep an eye out in the logs for any new packages that you've added since your previous successful build. Run
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 you can search the forums
and GitHub issues for related packages to dig deeper. Some common sources of problems are listed below.
📦 Are you using a monorepo?
Monorepos are incredibly useful but they do introduce their own set of problems. A monorepo that you have set up to work with
expo build will not necessarily work with
With EAS Build, it's necessary to upload the entire monorepo to the build worker, set it up, and run the build; but, on
💥 Out-of-memory (OOM) errors
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:
- Relevant Build tool versions (eg: Xcode, Node, npm, Yarn) are the same in both environments. Learn more.
- Relevant environment variables are the same in both environments. Learn more.
- The archive that is uploaded to EAS Build includes the same relevant source files. Learn more.
You can verify that your project builds on your local machine with the
commands with variant/configuration flags set to release to most faithfully reproduce what executes on EAS Build. (Learn more about the iOS build process
and Android build process
# Locally compile and run the Android app in release mode
expo run:android --variant release
# Locally compile and run the iOS app in release mode
expo run:ios --configuration Release
In managed projects, these commands will run
to generate native projects — you likely want to clean up the changes
once you are done troubleshooting.
💡 Don't have Xcode and Android Studio set up on your machine?
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 worker must set up its environment, download your project, and install dependencies before starting the build.
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, StackOverflow, and GitHub Issues.
If you find yourself in this situation, 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.
There are two ways to approach this, which are quite similar:
- Do a fresh
git clone of your project to a new directory and get it running. Pay attention to each of the steps that are needed and verify that they are also configured for EAS Build.
- Run a local build with
eas build --local. This command will locally run a process that is as close as it can be to the remote, hosted EAS Build service. Learn how to set this up and use it for debugging.
The classic build service (
) works completely differently from EAS Build, and there is no guarantee that your app will work out of the box on EAS Build if it works on the classic build service. You can learn more about migrating from
expo build in the guide
, and get a better understanding of how these two services are fundamentally different in this two-part blog post
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
or the 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
When you ask for troubleshooting help, be sure to share the following information:
- A link to your build page. This can only be accessed by your team or Expo employees. If you'd like to share it more publicly, take a screenshot. If you'd like to share it more privately, send an email to firstname.lastname@example.org and mention that in your help request on chat or forums. If you are performing this build locally with
eas build --local, you may omit this, but please indicate this fact.
- Error logs. Anything that you suspect may be related to your build or runtime error. If you can't provide this, please explain why not.
- Minimal reproducible example or a link to your repository. The quickest way to get a solution to your problem is to ensure that other developers can reproduce it. If you have ever worked on a team, you know this from experience. In many cases, if you can't provide a reproducible example then it may not be possible to help you, and at best the back-and-forth process of asking and answering questions will be an inefficient use of time. Learn more about how to create a reproducible example in the manual debugging guide and StackOverflow's "Minimal Viable Reproducible Example" guide.