--- 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 ```bash # 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 ```bash # List connected devices adb devices # Restart adb server adb kill-server adb start-server # Connect to device over network adb connect :5555 # Check device info adb shell getprop ro.build.version.release ``` #### App Debugging ```bash # Install debug APK flutter install # Run with debug logging flutter run -d --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 ```bash # 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 ```bash # Clean and rebuild flutter clean cd android ./gradlew clean cd .. flutter pub get flutter build apk ``` **Issue**: Dependency conflicts ```bash # Check dependencies cd android ./gradlew app:dependencies # Update Gradle cd android ./gradlew wrapper --gradle-version=8.0 ``` **Issue**: Java version mismatch ```bash # 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 1. Check logs: `flutter logs` 2. Look for stack traces 3. Check `AndroidManifest.xml` permissions 4. Verify minimum SDK version in `android/app/build.gradle.kts` **Issue**: Platform channel errors 1. Verify method names match between Dart and Kotlin/Java 2. Check parameter types are compatible 3. Add null safety checks 4. Review platform-specific code in `android/app/src/main/kotlin/` #### Performance Issues **Issue**: UI lag or jank ```bash # Run in profile mode flutter run --profile # Enable performance overlay flutter run --profile --trace-skia ``` **Issue**: Memory leaks 1. Use Flutter DevTools Memory tab 2. Check for retained references 3. Dispose controllers properly 4. Review image caching **Issue**: Large APK size ```bash # Analyze size flutter build apk --analyze-size # Enable R8 shrinking (already enabled in template) # Check android/app/build.gradle.kts ``` ### 5. Using Flutter DevTools ```bash # 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 1. Open `android/` folder in Android Studio 2. Use Android Profiler for deep analysis 3. Run layout inspector 4. Use APK Analyzer #### ADB Commands ```bash # 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.private_chat_hub # Force stop app adb shell am force-stop com.cmwen.private_chat_hub # Clear app data adb shell pm clear com.cmwen.private_chat_hub # 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 1. **Always check Flutter doctor first**: `flutter doctor -v` 2. **Use verbose logging**: `flutter run --verbose` or `flutter build apk --verbose` 3. **Clean before rebuild**: `flutter clean` when in doubt 4. **Check device connection**: `flutter devices` and `adb devices` 5. **Read full stack traces**: Don't just look at the first error 6. **Test on multiple Android versions**: Emulators for API 21, 29, 33+ 7. **Use profile mode for performance**: `flutter run --profile` 8. **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 ## Additional Resources - [Flutter Debugging Docs](https://docs.flutter.dev/testing/debugging) - [Android Developer Debug Guide](https://developer.android.com/studio/debug) - [Flutter DevTools](https://docs.flutter.dev/tools/devtools) - [ADB Reference](https://developer.android.com/tools/adb) --- Source attribution: cmwen Original project: https://github.com/cmwen/private-chat-hub/blob/455b8c7e6b8a126a65c3f4bf85f31adeae61f848/.github/skills/android-debug/SKILL.md License: MIT License information: https://opensource.org/license/mit Original upstream instructions; downloaded from Dave AI. ## Upstream license notice MIT License Copyright (c) 2024 cmwen Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. # Dave AI resource metadata Creator / publisher: cmwen Original project: https://github.com/cmwen/private-chat-hub/blob/455b8c7e6b8a126a65c3f4bf85f31adeae61f848/.github/skills/android-debug/SKILL.md Attribution basis: Recovered original package and original project license at a pinned revision Fields of work: Development & Engineering Roles: Backend Developer, Mobile Developer Specialties: Backend, Mobile Tools: Tool not specified Country applicability: Country not specified Classification basis: Source catalog labels Instruction SHA-256: 6a7624870075ec406105f47e1791e68189cdf0a02da9babf5bd6b2443e9529b9 Metadata reviewed: 2026-10-27 This metadata supersedes earlier Dave AI catalog attribution. Original instruction and supporting files are preserved.