name	android-debug
description	Debug Android Flutter apps including runtime errors, build issues, device connection problems, and performance issues. Use when troubleshooting Android-specific problems, crashes, or deployment issues.

Android App Debugging Skill

Expert guidance for debugging Android Flutter applications, covering runtime errors, build issues, device connectivity, and performance problems.

When to Use This Skill

App crashes or runtime errors on Android
Build failures in Android-specific code
Device/emulator connection issues
Performance problems (lag, memory, battery)
Platform channel issues
Native Android integration bugs
APK/App Bundle generation problems

Debugging Workflow

1. Identify the Problem Type

Runtime Errors: App crashes, exceptions, unexpected behavior Build Errors: Gradle failures, dependency conflicts, compilation errors Device Issues: Cannot connect, not detecting device Performance Issues: Slow UI, memory leaks, battery drain

2. Gather Information

# Check Flutter doctor
flutter doctor -v

# List connected devices
flutter devices

# Run with verbose logging
flutter run --verbose

# Check Android logcat
flutter logs
# Or directly: adb logcat

3. Common Debug Commands

Device Connection

# List connected devices
adb devices

# Restart adb server
adb kill-server
adb start-server

# Connect to device over network
adb connect <device-ip>:5555

# Check device info
adb shell getprop ro.build.version.release

App Debugging

# Install debug APK
flutter install

# Run with debug logging
flutter run -d <device-id> --verbose

# Hot reload
r (in running flutter session)

# Hot restart
R (in running flutter session)

# View performance overlay
P (in running flutter session)

Log Analysis

# Filter logs by app
flutter logs | grep -i "flutter"

# Android-specific logs
adb logcat -s flutter

# Clear logs
adb logcat -c

# Save logs to file
adb logcat > debug.log

4. Common Issues and Solutions

Build Failures

Issue: Gradle build fails

# Clean and rebuild
flutter clean
cd android
./gradlew clean
cd ..
flutter pub get
flutter build apk

Issue: Dependency conflicts

# Check dependencies
cd android
./gradlew app:dependencies

# Update Gradle
cd android
./gradlew wrapper --gradle-version=8.0

Issue: Java version mismatch

# Check Java version (should be 17)
java -version

# Set JAVA_HOME if needed
export JAVA_HOME=/path/to/java17

Runtime Crashes

Issue: App crashes on startup

Check logs: flutter logs
Look for stack traces
Check AndroidManifest.xml permissions
Verify minimum SDK version in android/app/build.gradle.kts

Issue: Platform channel errors

Verify method names match between Dart and Kotlin/Java
Check parameter types are compatible
Add null safety checks
Review platform-specific code in android/app/src/main/kotlin/

Performance Issues

Issue: UI lag or jank

# Run in profile mode
flutter run --profile

# Enable performance overlay
flutter run --profile --trace-skia

Issue: Memory leaks

Use Flutter DevTools Memory tab
Check for retained references
Dispose controllers properly
Review image caching

Issue: Large APK size

# Analyze size
flutter build apk --analyze-size

# Enable R8 shrinking (already enabled in template)
# Check android/app/build.gradle.kts

5. Using Flutter DevTools

# Open DevTools
flutter pub global activate devtools
flutter pub global run devtools

# Or run automatically
flutter run --devtools

DevTools Features:

Inspector: Widget tree visualization
Timeline: Performance profiling
Memory: Heap snapshots and leak detection
Network: HTTP request monitoring
Logging: Real-time log viewing
Debugger: Breakpoints and step debugging

6. Android-Specific Debug Tools

Android Studio

Open android/ folder in Android Studio
Use Android Profiler for deep analysis
Run layout inspector
Use APK Analyzer

ADB Commands

# Take screenshot
adb shell screencap /sdcard/screen.png
adb pull /sdcard/screen.png

# Record screen
adb shell screenrecord /sdcard/demo.mp4

# Get app info
adb shell dumpsys package com.cmwen.min_flutter_template

# Force stop app
adb shell am force-stop com.cmwen.min_flutter_template

# Clear app data
adb shell pm clear com.cmwen.min_flutter_template

# Monitor CPU usage
adb shell top | grep flutter

Common Error Patterns

Gradle Errors

Solution: Clean build, check Java version, update dependencies
Files to check: android/build.gradle.kts, android/app/build.gradle.kts

Permission Errors

Solution: Add permissions to AndroidManifest.xml
File: android/app/src/main/AndroidManifest.xml

Native Code Errors

Solution: Check Kotlin/Java code in platform channels
Files: android/app/src/main/kotlin/

Resource Errors

Solution: Check drawable/mipmap resources
Files: android/app/src/main/res/

Best Practices

Always check Flutter doctor first: flutter doctor -v
Use verbose logging: flutter run --verbose or flutter build apk --verbose
Clean before rebuild: flutter clean when in doubt
Check device connection: flutter devices and adb devices
Read full stack traces: Don't just look at the first error
Test on multiple Android versions: Emulators for API 21, 29, 33+
Use profile mode for performance: flutter run --profile
Enable DevTools: Best for deep debugging

Quick Troubleshooting Checklist

Run flutter doctor -v - all green?
Run flutter clean && flutter pub get
Check adb devices - device connected?
Check Java version - is it 17?
Review error logs - full stack trace?
Try on different device/emulator
Check android/app/build.gradle.kts config
Verify AndroidManifest.xml settings
Test with flutter run --verbose
Use DevTools for deep analysis

android-debug

Install Skill

SKILL.md