Debugging runtime issues

Learn about different techniques available to debug your Expo project.

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 into two categories:

• Errors you encounter in the development
• Errors you (or your users) encounter in production

Let's go through recommended practices when dealing with each of the above situations.

Development errors

They are common errors that you encounter while developing your app. Delving into them isn't always straightforward. Usually, debugging when running your app with Expo CLI is enough.

One way you can debug these issues is by looking at the stack trace. However, in some scenarios, looking at the stack trace isn't enough as the error message traced might be a little more cryptic. For such errors, follow the steps below:

• 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 to a working version of your code. This may even be a completely blank npx create-expo-app 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 such as Redux, you can try removing that from the equation completely to see if the issue lies in your state management (which is 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, however, it's fast, easy, and oftentimes provides some illuminating information.

Simplifying code as much as possible to track down the source of error is a great way to debug your app and it gets exponentially easier. That's why many open-source repositories require a minimal reproducible example when you open an issue. It ensures you have isolated the issue and identified exactly where the problem occurs. If your app is too large and complex to do that, try and extract the functionality you're trying to add in a blank npx create-expo-app project, and go from there.

Native debugging

You can perform full native debugging with Android Studio and Xcode by generating source code locally and building from that source.

Android Studio

You can delete the android directory when you are done with this process. This ensures that your project remains managed by Expo CLI. Keeping the directory around and manually modifying it outside of npx expo prebuild means you'll need to manually upgrade and configure native libraries yourself.

Xcode

This is only available for macOS users and requires Xcode to be installed.

You can delete the ios directory when you are done with this process. This ensures that your project remains managed by Expo CLI. Keeping the directory around and manually modifying it outside of npx expo prebuild means you'll need to manually upgrade and configure native libraries yourself.

Production errors

Errors or bugs in your production app can be much harder to solve, mainly because you have less context around the error (that is, 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.

Tip: Sometimes, running your app in production mode locally will show errors that normally wouldn't be thrown. You can run the app locally in production by running npx expo start --no-dev --minify. --no-dev tells the server not to be run in development mode, and --minify is used to minify your code the same way it is for production JavaScript bundles.

Production app is crashing

It can be a frustrating scenario when a production app crashes. There is very little information to look into when it happens. It's important to reproduce the issue, and even if you can't do that, to find any related crash reports.

Start by reproducing the crash using your production app and then find an associated crash report. For Android, you can use adb logcat and for iOS you can use the Console app in Xcode.

How to use Logcat & macOS Console to debug

In this tutorial, you'll learn how to use native device logging features like ADB Logcat and macOS Console to find bugs in your code and quickly fix them.

Crash reports using adb logcat

If your Android app is on Google Play, refer to the crashes section of the Google Play Console, or connect your Android device to your computer and run the following command:

The Android Debug Bridge (adb) program is part of the Android SDK and allows you to view streaming logs. An alternative to avoid installing Android SDK is to use WebADB in Chrome.

Crash reports using Console app

If your iOS app is on TestFlight or the App Store, you can use the Crashes Organizer in Xcode.

If not, you can use the Console app in Xcode by connecting your device to your Mac. Follow the steps below on how to access the Console app:

2

If you have connected a physical device, select it under Devices. Otherwise, if you are using a simulator, select it under Simulators.

3

Click on Open Console button shown in the window to open the console app.

This will open the console app for you to view logs from your device or simulator.

For more information, see Apple's Diagnosing Issues Using Crash Reports and Device Logs guide.

App crashes on certain (older) devices

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.

Using error reporting services

Implementing a crash and bug reporting service in your production app offers several benefits, such as:

• Real-time insights on production deployments with information to reproduce crashes and bugs.
• Setting up an alert system to get notified about fatal JavaScript errors or any other event you configure.
• Using a web dashboard to see details on exceptions such as stack traces, device information, and so on.

With Expo, you can integrate a reporting service like Sentry or BugSnag to get more insights in real-time.

Stuck?

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 same error as you, so make sure to read the documentation, search the forums, GitHub issues, and Stack Overflow.