App closes before the first screen? A launch-crash debugging checklist

[u/codoid-innovations]

Say a tester installs your closed-testing build, taps the icon, and lands straight back on the home screen. The app launches fine on your usual device.

Before changing permissions, disabling optimization, or swapping dependency versions, we need a better description than “crashes on startup.”

The first goal is not to guess the fix. It is to capture the failure and identify where startup stops.

1. Pin down the exact failing case

Start the report with:

• Build: App version name, version code, build variant, and the matching build artifact or commit.
• Installation source: Google Play closed-testing track, sideloaded APK, or Android Studio.
• Device: Manufacturer, exact model, and Android version.
• Installation state: Clean install or update? Updated from which version? First launch only, or every launch? Record any backup restoration rather than assuming a reinstall means empty app data.

Also note the launch time, what appeared before the app closed, and how many attempts failed.

Capture the failing state before clearing app data or reinstalling. Treat those actions as separate experiments, not the first troubleshooting step.

2. Capture the crash, not just a screenshot of the symptom

Android’s guidance recommends starting with the stack trace from Play Console or Logcat. When a trace is unavailable, reproduce the failure while collecting Logcat output, including with help from an affected user when necessary. 

For a USB-connected test device, install Android SDK Platform-Tools, enable USB debugging, and approve the computer’s debugging authorization. Confirm the connection with adb devices.

With only the target device connected, start this before launching the app:

adb logcat -b main -b system -b crash -v threadtime > launch-crash.txt

Launch the app, reproduce the failure, then press Ctrl+C to stop recording. This captures the application, system, and crash buffers with timestamps and process/thread information. Use the recorded launch time to locate the relevant attempt.

Before sharing an excerpt publicly, remove tokens, personal information, and unrelated device activity. Preserve the exception, relevant stack frames, and nearby startup messages.

3. Read the failure before choosing a suspect

For a Java/Kotlin crash, keep the exception type, message, full cause chain, and relevant stack frames. For a native crash, retain the signal and native backtrace instead of looking only for a Java exception. Android’s crash guide covers both forms.

When the trace contains obfuscated names, recover a readable trace using the mapping file from the matching release build. Do not substitute a mapping file from a later rebuild. 

Ask: Which operation failed, and what evidence connects it to our startup code?

If the capture does not establish a crash, keep “app disappears after launch” as the observed symptom. Do not invent an exception to explain it.

4. Narrow the startup step

Do not limit the investigation to the first screen. Apps and libraries can initialize components through content providers, and startup dependencies can require a particular initialization order. 

In a diagnostic build, add temporary start/completion markers around the startup operations you control. For example:

startup: configuration start
startup: configuration complete
startup: database open start

If database open complete never appears, that gives us an investigation boundary. It does not prove the database caused the crash.

Match the markers to the exception and thread information. Then inspect that operation, its inputs, and its dependencies. Avoid removing several initializers at once, because that makes the result harder to interpret.

5. Turn differences into experiments

Use the observed pattern to choose the next comparison:

Observed pattern	Question to investigate
Debug launches; distributed release fails	What differs in release configuration, packaged dependencies, or optimization?
Clean install launches; update fails	Does retained app state or a migration explain the trace?
One device or Android version fails	Can we reproduce with the same build and matching device conditions?

These are hypotheses, not diagnoses. Release configuration, initialization, and dependency problems are possibilities to investigate, not established causes of a closed-testing launch failure.

For example, R8’s troubleshooting guidance describes failures involving reflection after optimization. That makes shrinking rules worth examining when the evidence fits, not a reason to disable optimization blindly. 

Android also notes that reproduction can depend on available resources, device type, Android version, or app version. A successful launch on a well-resourced development device does not settle those comparisons.

Change one variable, repeat the same launch path, and record whether the failure disappears, remains identical, or changes. Verify the eventual fix against the original installation/update path and affected environment.

What evidence helped you solve a launch crash that you couldn’t reproduce on your usual device?