An Android app crashes whenever there’s an unexpected exit caused by an
unhandled exception or signal. An app that is written using Java crashes if it
throws an unhandled exception, represented by the
class. An app that is written using native-code languages crashes if there’s an
unhandled signal, such as SIGSEGV, during its execution.
When an app crashes, Android terminates the app's process and displays a dialog to let the user know that the app has stopped, as shown in figure 1.
An app doesn’t need to be running in the foreground for it to crash. Any app component, even components like broadcast receivers or content providers that are running in the background, can cause an app to crash. These crashes are often confusing for users because they were not actively engaging with your app.
If your app is experiencing crashes, you can use the guidance in this page to diagnose and fix the problem. For guidance on how to diagnose crashes in apps built using native-code languages, see Diagnosing native crashes.
Detect the problem
You may not always know that your users are experiencing an inordinate number of crashes with your app. If you have already published your app, Android vitals can help make you aware of the problem.
Android vitals can help improve your app's performance by alerting you, via the Play Console, when your app is exhibiting excessive crashes. Android vitals considers crashes excessive when an app:
- Exhibits at least one crash in at least 1.09% of its daily sessions.
- Exhibits two or more crashes in at least 0.18% of its daily sessions.
A daily session refers to a day in which your app was used. For information on how Google Play collects Android vitals data, see the Play Console documentation.
After you learn that your app is suffering from too many crashes, the next step is to diagnose them.
Diagnose the crashes
Solving crashes can be difficult. However, if you can identify the root cause of the crash, most likely you can find a solution to it.
There are many situations that can cause a crash in your app. Some reasons are obvious, like checking for a null value or empty string, but others are more subtle, like passing invalid arguments to an API or even complex multithreaded interactions.
Reading a stack trace
The first step to fix a crash is to identify the place where it happens. You can use the stack trace available in the report details if you are using Play Console or the output of the logcat tool. If you don’t have a stack trace available, you should locally reproduce the crash, either by manually testing the app or by reaching out to affected users, and reproduce it while using logcat.
The following trace shows an example of a crash on a sample app:
--------- beginning of crash AndroidRuntime: FATAL EXCEPTION: main Process: com.android.developer.crashsample, PID: 3686 java.lang.NullPointerException: crash sample at com.android.developer.crashsample.MainActivity$1.onClick(MainActivity.java:27) at android.view.View.performClick(View.java:6134) at android.view.View$PerformClick.run(View.java:23965) at android.os.Handler.handleCallback(Handler.java:751) at android.os.Handler.dispatchMessage(Handler.java:95) at android.os.Looper.loop(Looper.java:156) at android.app.ActivityThread.main(ActivityThread.java:6440) at java.lang.reflect.Method.invoke(Native Method) at com.android.internal.os.Zygote$MethodAndArgsCaller.run(Zygote.java:240) at com.android.internal.os.ZygoteInit.main(ZygoteInit.java:746) --------- beginning of system
A stack trace shows two pieces of information that are critical to debugging a crash:
- The type of exception thrown.
- The section of your of the code where the exception is thrown.
The type of exception thrown is usually a very strong hint as to what went
wrong. Look at whether it is an
OutOfMemoryError, or something else, and find the
documentation about the exception class.
The class, method, file a line number of the source file where the exception is thrown is shown on the second line of a stack trace. For each function that was called, another line shows the preceding call site (called a stack frame). By walking up the stack and examining the code, you may find a place that is passing an incorrect value. If your code doesn’t appear in the stack trace, it is likely that somewhere, you passed an invalid parameter into an asynchronous operation. You can often figure out what happened by examining each line of the stack trace, finding any API classes that you used, and confirming that the parameters you passed were correct, and that you called it from a place that is allowed.
For more information about crashes on native apps, see Diagnosing native crashes.
Tips for reproducing a crash
It’s possible that you can’t quite reproduce the problem just by starting an emulator or connecting your device to your computer. Development environments tend to have more resources, such as bandwidth, memory, and storage. Use the type of exception to determine what could be the resource that is scarce, or find a correlation between the version of Android, device type or your app’s version.
If you have an
OutOfMemoryError, then you could create an
emulator with low memory capacity to begin with. Figure 2 shows the AVD manager
settings where you can control the amount of memory on the device.
Since users frequently move in and out of mobile or WiFi network coverage, in an application network exceptions usually should not be treated as errors, but rather as normal operating conditions that happen unexpectedly.
If you need to reproduce a network exception, such as
UnknownHostException, then try turning on airplane mode while your
application attempts to use the network.
Another option is to reduce the quality of the network in the emulator by
choosing a network speed emulation and/or a network delay. You can use the
Speed and Latency settings on AVD manager, or you can start the emulator
-netspeed flags, as shown in the following
emulator -avd [your-avd-image] -netdelay 20000 -netspeed gsm
This example sets a delay of 20 seconds on all network requests and an upload and download speed of 14.4 Kbps. For more information on command-line options for the emulator, see Start the Emulator from the Command Line.
Reading with logcat
Once you are able have the steps to reproduce the crash, you can use a tool like logcat to get more information.
The logcat output will show you what other log messages you have printed, along
with others from the system. Don’t forget to turn off any extra
Log statements that you have added because printing them wastes
CPU and battery while your app is running.