Capture and Analyze Android Crash Logs with ADB and Logcat

Why you need crash logs

When an app suddenly stops, freezes, or crashes, Android records a detailed trace in the system log. Those traces—known as logcat output—contain the exception type, stack trace, thread state, and often the exact line of code that caused the failure. Accessing that information lets you pinpoint the problem, verify whether it’s a bug in the app or a device‑specific issue, and communicate clear data to developers or support teams.

Before you start

• Backup important data. While capturing logs never modifies device storage, you’ll be toggling developer options and possibly clearing the log buffer.
• Use a charged USB cable and a computer with a stable internet connection to download the ADB platform‑tools.
• Have a text editor (e.g., VS Code, Notepad++, or even Notepad) ready to open the saved .txt log files.
• If you plan to decode obfuscated stack traces, locate the mapping.txt file generated when the app was built with ProGuard/R8.

1. Install the Android Debug Bridge (ADB)

ADB is part of the Android SDK Platform‑Tools package. It works on Windows, macOS, and Linux.

1. Download the latest platform-tools zip from the official Android developer site (developer.android.com).
2. Extract the zip to a convenient location, e.g., C:\adb on Windows or ~/adb on macOS/Linux.
3. Add the folder to your system PATH so you can run adb from any terminal.
   • Windows: Open System Properties → Advanced → Environment Variables → Path → New → C:\adb.
   • macOS/Linux: Add export PATH=$PATH:~/adb to your ~/.bashrc or ~/.zshrc and reload the shell.
4. Open a terminal (Command Prompt, PowerShell, Terminal) and verify the installation:

   adb version

   You should see something like Android Debug Bridge version 1.0.41.

2. Enable USB debugging on the Android device

USB debugging gives ADB permission to communicate with the phone.

1. Open Settings → About phone.
2. Find Build number and tap it seven times. You’ll see a toast: “You are now a developer!”.
3. Return to the main Settings screen; a new entry Developer options appears.
4. Enter Developer options and toggle USB debugging on.
   • On some OEM skins the wording may be “Android debugging” or “USB debugging (Security settings)”.
5. When you connect the phone to the PC for the first time, a dialog asks “Allow USB debugging?” – tap Allow and optionally check “Always allow from this computer”.

3. Verify the device connection

adb devices

The command should list a device ID followed by device. Example:

List of devices attached
R58M7XXXX    device

If you see unauthorized, check the phone’s dialog and tap Allow. If the list is empty, try the following:

• Reconnect the USB cable and ensure it’s a data‑capable cable (not a charge‑only cable).
• On Windows, install the appropriate OEM USB driver (Google USB Driver for Nexus/Pixel, Samsung USB driver for Galaxy, etc.).
• On macOS/Linux, ensure you have the correct udev rules (Linux) or that the device appears in system_profiler SPUSBDataType (macOS).

4. Capture a live logcat stream

Now that ADB sees the device, you can start pulling logs.

1. Open a terminal window and run:

   adb logcat

   This prints an endless stream of log lines.
2. Reproduce the crash on the device while the stream is running. Typical log lines look like:

   04-12 14:23:45.678  1234  5678 E/AndroidRuntime: FATAL EXCEPTION: main
   04-12 14:23:45.679  1234  5678 E/AndroidRuntime: Process: com.example.app, PID: 1234
   04-12 14:23:45.680  1234  5678 E/AndroidRuntime: java.lang.NullPointerException: Attempt to invoke virtual method 'int java.lang.String.length()' on a null object reference
   04-12 14:23:45.681  1234  5678 E/AndroidRuntime: 	at com.example.app.ui.MainActivity.onCreate(MainActivity.java:45)

3. Press Ctrl+C to stop the stream once the crash has been reproduced.

5. Save the log to a file for later analysis

Instead of watching the stream, you can write it directly to a file.

adb logcat -d > crash_log.txt

The -d flag tells ADB to dump the current buffer and exit. If you want a continuous capture, omit -d and redirect:

adb logcat > crash_log.txt

When you’re done, stop with Ctrl+C. Transfer the file to your PC (it’s already there if you ran the command on the PC) and open it with any text editor.

6. Filtering logcat output

Logcat is noisy; a typical Android session generates thousands of lines per minute. Filtering helps you focus on the crash.

6.1 By log level

adb logcat *:E

Shows only entries with priority E (Error) or higher.

6.2 By tag

Most crash reports are tagged AndroidRuntime. Use:

adb logcat AndroidRuntime:E *:S

*:S silences all other tags.

6.3 By process ID (PID)

If you know the app’s PID (visible in the crash lines), you can filter:

adb logcat --pid=1234

6.4 Combining filters

Example – show errors from the target app only:

adb logcat -v threadtime AndroidRuntime:E *:S --pid=1234

The -v threadtime format adds timestamp, PID, and TID, which is useful for correlating events.

7. Decoding a stack trace

When the app is built with code shrinking (ProGuard or R8), the stack trace shows obfuscated class and method names like a.b.c. To translate them back you need the mapping.txt file produced at build time.

1. Locate mapping.txt in the app/build/outputs/mapping/release/ directory of the original APK project.
2. Download the retrace tool that ships with the Android SDK (found under tools/proguard/bin/retrace).
3. Run:

   retrace -verbose mapping.txt crash_log.txt > decoded_log.txt

   The output replaces obfuscated symbols with the original names.

8. Using Android Studio’s Logcat viewer (optional)

If you already have Android Studio, its built‑in Logcat UI provides colour‑coded filtering, search, and the ability to copy stack traces directly.

1. Connect the device, launch Android Studio, and open View → Tool Windows → Logcat.
2. Select your device and app process from the dropdowns.
3. Use the filter field (e.g., level:error or tag:AndroidRuntime) to narrow results.
4. Click the small save icon to export the view to a .txt file.

Android Studio also lets you paste a stack trace into the Analyze → Analyze Stack Trace dialog, which automatically links to the source code if you have the project opened.

9. Common issues and troubleshooting

9.1 Device not listed by adb devices

• Make sure the USB cable is a data cable.
• On Windows, install the OEM USB driver or the generic Google USB driver via the SDK Manager.
• On Linux, add a udev rule for your vendor ID. Example rule:

  SUBSYSTEM=="usb", ATTR{idVendor}=="18d1", MODE="0666", GROUP="plugdev"

• Restart the ADB server:

  adb kill-server
  adb start-server

9.2 Permission denied when running adb logcat

Some manufacturers (e.g., Xiaomi, Huawei) add a secondary “Log access” toggle under Developer options. Enable it. If the device still blocks access, you may need to grant the android.permission.READ_LOGS permission, which is only available to system apps—so on stock devices you’re limited to your own app’s logs. In that case, use adb shell setprop log.tag.YOUR_TAG DEBUG to increase verbosity for your own tags.

9.3 Log buffer overflow

If you capture logs for a long period, the circular buffer may overwrite older lines before you can save them. To avoid loss:

• Clear the buffer before reproducing the crash: adb logcat -c.
• Capture to a file directly (see section 5) instead of relying on the in‑memory dump.

9.4 Missing stack trace details

Some crashes are caught by the system and reported only as a short “App has stopped” toast. In those cases, enable the “Show system” filter in Logcat or use adb shell dumpsys activity crashes to retrieve the last crash report.

10. Best practices for effective debugging

• Reproduce consistently. If the crash only happens under certain conditions (low memory, specific network state), script those steps before you start logging.
• Clear the log buffer. Run adb logcat -c each time you begin a new test to avoid mixing old entries.
• Use descriptive tags. When developing your own app, add Log.e("MyFeature", "Something went wrong", e) so you can filter by MyFeature later.
• Capture the full device state. Alongside logcat, run adb shell dumpsys battery, adb shell dumpsys meminfo, and adb shell getprop to collect context that may influence the crash.
• Keep logs secure. Crash logs can contain personal data (e.g., usernames, tokens). Store them in an encrypted folder if you plan to share them.

11. Privacy and security considerations

Logcat records everything that apps write to the system log, including potentially sensitive information such as API keys, user identifiers, or location data. Treat logs as confidential:

• Never upload raw logs to public forums.
• Redact personal identifiers before sharing with developers.
• If you suspect a malicious app is dumping data, consider revoking its permissions or uninstalling it.

12. When to involve the app developer

After you have a clear stack trace and, if applicable, a deobfuscated version, you can provide the developer with:

1. The filtered logcat excerpt (use adb logcat -d AndroidRuntime:E *:S).
2. Device model, Android version, and any custom ROM details.
3. Steps to reproduce the crash.
4. Any additional dumps you collected (battery, memory, etc.).

This information often lets developers locate the offending line of code within minutes.

Summary

Capturing and analyzing Android crash logs with ADB and Logcat is a powerful, no‑root method for troubleshooting app failures. By installing ADB, enabling USB debugging, clearing the log buffer, reproducing the crash, and then filtering or deobfuscating the output, you gain a clear view into what the system saw at the moment of failure. The workflow described here works across manufacturers and Android versions, and the added troubleshooting tips help you overcome the most common obstacles.

Armed with these logs, you can either fix the issue yourself (if you’re a developer) or provide developers with the exact data they need to issue a fix. Remember to handle logs responsibly, keep your debugging tools up to date, and disable USB debugging when you’re done.