Whether you're developing your app locally, sending it out to select beta testers, or launching your app live to the app stores, you'll always find yourself debugging issues. It's useful to split errors out into two categories:
- Errors you encounter in development
- Errors you (or your users) encounter in production
Let's go through some of our recommended practices when it comes to each of these situations, and at the end of this guide, we'll recommend tools that can make debugging easier.
Sometimes you'll be able to tell exactly what's wrong just by the stacktrace
, but other times the error message is a little more cryptic. For errors that aren't as intuitive to solve, here's a good list of steps to take:
- Search for the error message in Google and Stack Overflow, it's likely you're not the first person to ever run into this
- Isolate the code that's throwing the error. This step is vital in fixing obscure errors. To do this:
- Revert back to a working version of your code (this may even be a completely blank
expo init project)
- Apply your recent changes piece by piece, until it breaks
- If the code you're adding in each "piece" is complex, you may want to simplify what you're doing. For example, if you use a state management library like Redux, you can try removing that from the equation completely to see if the issue lies in your state management (which is really common in React apps)
- This should narrow down the possible sources of the error, and provide you with more information to search the internet for others who have had the same problem
- Use breakpoints (or
console.logs) to check and make sure a certain piece of code is being run, or that a variable has a certain value. Using
console.log for debugging isn't considered the best practice, but it's fast, easy, and oftentimes provides some illuminating information
If you are able to simplify your code as much as possible, tracking down the source of an error gets exponentially easier. That's exactly why so many open source repos require a minimal reproducible demo
in their bug reports- it ensures you have isolated the issue and identified exactly where the problem lies! If your app is too large and complex to do that, try and extract the functionality you're trying to add to it's own blank
project, and go from there.
Errors or bugs in your production app can be much harder to solve, mainly because you have less context around the error (i.e. where, how, and why did the error occur?). The best first step in addressing a production error is to reproduce it locally.
Once you reproduce an error locally, you can follow the development debugging process
to isolate and address the root cause.
Hint: sometimes, running your app in "production mode" locally will show errors that normally wouldn't be thrown. You can run an app locally in production by running
Using an automated error logging system like Sentry
Sentry is one of those tools that if you wait until you need it to install it, then you waited too long. Also- Sentry is free up to 5000 events/month.
This can be a really frustrating scenario, since it gives you very little information to go off of on first glance. But, in reality, crashes can be one of the easiest-to-solve errors once you:
- Access the native device logs
- Reproduce the crash (either using your production app, or the Expo client app)
- Search the logs for a "fatal exception" (there could be a few) to see exactly what is causing your app to crash
With that information, you should be able to identify where the error is coming from, or at least search the internet for possible causes & solutions.
This might indicate that there is a performance issue. You likely need to run your app through a profiler to get a better idea of what processes are killing the app, and React Native provides some great documentation for this
. We also recommend using React Devtools
and the included profiler, which makes it super easy to identify performance sinks in your app.
The Expo community and the React and React Native communities are great resources for help when you get stuck. There's a good chance someone else has run into the exact same error as you, so make sure to read the documentation, search the forums
, Github issues
, and StackOverflow
Below are a few tools we recommend, and use ourselves, when it comes to debugging your Expo app:
This menu gives you access to several functions which are useful for debugging, and is built into the Expo client app. The way you open it is a bit different depending on where you're running the Expo client:
- iOS Device: Shake the device a little bit, or touch 3 fingers to the screen.
- iOS Simulator: Hit
Ctrl-Cmd-Z on a Mac in the emulator to simulate the shake gesture, or press
- Android Device: Shake the device vertically a little bit, or run
adb shell input keyevent 82 in your terminal window if your device is connected via USB.
- Android Emulator: Either hit
Cmd+M, or run
adb shell input keyevent 82 in your terminal window.
The Developer Menu gives you a couple different functionalities. A few are pretty self-explanatory, like:
- Reload manifest & JS bundle: this will reload your app. Usually this isn't necessary if you have Live or Hot Reload enabled, since it will automatically refresh whenever you save your changes in your text editor.
- Go to Expo Home: Leave your app and navigate back to the Expo client homescreen
- Enable/Disable Live Reload: When enabled, your app will automatically refresh the JS bundle whenever you save file changes in your project directory.
: In order to use Live Reload, your components must be class
components, rather than a functional components. You can read about their differences here
Now let's explore some of the more exciting functionalities...
This opens up a small window giving you performance information of your app. You will see:
- RAM usage of your project
- 2 numbers for Views, the top indicates the number of views for the screen, the bottom indicates the number of views in the component
- Frames Per Second for the UI and JS threads. The UI thread is used for native Android or iOS UI rendering. The JS thread is where most of your logic will be run, including API calls, touch events, etc.
Both of these work best in tandem with either
react-devtools. Read on to see more!
The React Native Debugger includes a lot of the tools listed later in this page, all bundled into one, including React-DevTools (guide below
) and network request inspection. For this reason, if you use one tool on this page, it should probably be this one!
We'll give a quick look at it here, but check out their documentation
for a more in-depth look.
You can install it via the release page
, or if you're on a mac you can run:
brew cask install react-native-debugger
After firing up React Native Debugger, you'll need to specify the port (shortcuts:
Command+T on macOS,
Ctrl+T on Linux/Windows) to
19000 (if you use SDK <= 39, the port should be
19001>). After that, run your project with
expo start, and select
Debug remote JS from the Developer Menu. The debugger should automatically connect.
In the debugger console, you can see the Element tree, as well as the props, state, and children of whatever element you select. You also have the Chrome console on the right, and if you type
$r in the console, you will see the breakdown of your selected element.
If you right-click anywhere in the React Native Debugger, you'll get some handy short-cuts to reload your JS, enable/disable the element inspector, network inspector, and to log and clear your
It's easy to use the React Native Debugger to debug your network requests. Simple right-click to
Enable Network Inspect
, which allows you to open the Network tab and inspect requests of
. There are some limitations
, so there are a few other alternatives, all require using a proxy. The following options will all work:
In bare workflow apps you can use Flipper
to inspect network traffic.
is a popular library for managing the state of your app that doesn't belong to any single component, and instead it shared throughout the app. You can use the React Native Debugger (told you this tool does it all), the set up is as follows:
- Download React Native Debugger from the releases page.
- Open the app, press
ctrl+t to open new window, then set the port to 19000.
- Start your app, open the in-app developer menu, and select “Debug JS Remotely.”
__REDUX_DEVTOOLS_EXTENSION__ as shown here.
You're now good to go! If you are experiencing any issues or want to learn more about how to use these tools, refer to this guide
React DevTools is a great way to get a look at each of your components' props and state. First, you'll need to run
npm install -g react-devtools
(if you don't want to install it globally, run
npm install --dev react-devtools to install it as a project dependency).
expo start in your project's root directory, use a separate terminal tab to run
react-devtools. This will open up the React Devtools console (for it to connect, you need to select
Debug remote JS from the Developer Menu in the Expo client). From this console, you can search for your React components at the top, or open up the Developer Menu and enable the Element Inspector. Once you do that, you can tap on any element on screen and React DevTools will automatically find and display that element in the tree. From there, you can inspect the elements state, props, etc.
React DevTools can also be paired with remote debugging, allowing you to inspect props, state, and instance properties in the Chrome console. If you have any questions on setting that up, give the next section a look!
To ensure the best debugging experience, first change your host type in Expo Dev Tools to
localhost. If you use
Tunnel with debugging enabled, you are likely to experience so much latency that your app is unusable. While here, also ensure that
Development Mode is checked.
If you are using
LAN, make sure your device is on the same wifi network as your development machine. This may not work on some public networks.
localhost will not work for iOS unless you are in the simulator, and it only work on Android if your device is connected to your machine via usb.
Open the app on your device, reveal the developer menu then tap on
Debug JS Remotely. This should open up a Chrome tab with the URL
Line numbers for
console.log statements don't work by default when using Chrome debugging. To get correct line numbers open up the Chrome Dev Tools settings, go to the "Blackboxing" tab, make sure that "Blackbox content scripts" is checked, and add
expo/build/logs/RemoteConsole.js as a pattern with "Blackbox" selected.
When you start a project with Expo CLI and when you press
Run on Android device/emulator in Expo Dev Tools (or
a in the terminal), Expo CLI will automatically tell your device to forward
localhost:19000 to your development machine, as long as your device is plugged in or emulator is running. If you are using
localhost for debugging and it isn't working, close the app and open it up again using
Open on Android. Alternatively, you can use the following
adb command if you have the Android developer tools installed:
adb reverse tcp:19000 tcp:19000.
Source maps and async functions aren't 100% reliable. React Native doesn't play well with Chrome's source mapping in every case, so if you want to make sure you're breakpointing in the correct place, you should use the
debugger call directly from your code.
In a perfect world, your app would ship without any bugs. However, that's usually not the case. So, it's usually a good idea to implement a crash and bug reporting system into your app. This way, if any user experiences a fatal JS error (or any event that you've configured to notify Sentry) you can see the details in your Sentry dashboard.
Expo provides a wrapper called sentry-expo
which allows you to get as much information as possible from crashes and other events. Plus, when running in the managed workflow, you can configure sourcemaps so that the stracktraces you see in Sentry will look much more like the code in your editor.