Skip to content

flutter_debug_guide.md

Latest commit

 

History

History
143 lines (103 loc) · 3.06 KB

flutter_debug_guide.md

File metadata and controls

143 lines (103 loc) · 3.06 KB
Raw

Flutter App Debugging Guide

Prerequisites

✅ Flutter SDK installed at: ~/Projects/flutter ✅ ADB installed and available ⚠️ Android device needs to be connected via USB with USB debugging enabled

Steps to Inspect Your Flutter App

1. Connect Your Android Device

  1. Enable Developer Options on your Android device:

    • Go to Settings → About Phone
    • Tap Build Number 7 times

  2. Enable USB Debugging:

    • Go to Settings → Developer Options
    • Enable USB Debugging

  3. Connect your device via USB cable

  4. Accept the USB debugging authorization prompt on your device

  5. Verify connection:

    adb devices

    You should see your device listed.

2. Find Your Running Flutter App

If your Flutter app is already running on your device, you need to find its process:

# List all running processes and filter for Flutter
adb shell ps | grep flutter

Or check for the Dart VM Observatory port:

# Forward the observatory port
adb forward tcp:8080 tcp:8080

3. Launch DevTools

Method A: Direct Launch

~/Projects/flutter/bin/flutter devtools

This will:

  • Start DevTools server
  • Open your browser to http://localhost:9100
  • Show you a connection screen

Method B: Connect to Running App

If your app is already running in debug mode, it should print an Observatory URL in the console like:

An Observatory debugger and profiler is available at: http://127.0.0.1:xxxxx/

Copy that URL and paste it into DevTools.

4. Alternative: Use ADB to Find the Observatory Port

# Check logcat for the Observatory URL
adb logcat | grep -i observatory

Or:

# List all forwarded ports
adb forward --list

5. Inspect Your App

Once connected to DevTools, you can:

  • Widget Inspector: View the widget tree, inspect properties, and debug layout issues
  • Performance: Profile your app's performance
  • Network: Monitor network requests
  • Logging: View console logs
  • Debugger: Set breakpoints and step through code (if you have the source)

Troubleshooting

Device Not Showing Up

# Restart ADB server
adb kill-server
adb start-server
adb devices

Can't Find Observatory URL

Your app must be built with debug mode enabled. Check that the app was built with:

  • flutter run --debug (if you built it yourself)
  • Or has debuggable true in the Android manifest

Port Forwarding Issues

# Forward a specific port
adb forward tcp:9100 tcp:9100

Quick Reference Commands

# Check Flutter version
~/Projects/flutter/bin/flutter --version

# Check connected devices
adb devices

# Launch DevTools
~/Projects/flutter/bin/flutter devtools

# View app logs
adb logcat

# Filter logs for Flutter
adb logcat | grep flutter

Add Flutter to PATH (Optional)

To use flutter command without the full path, add this to your ~/.zshrc:

export PATH="$PATH:$HOME/Projects/flutter/bin"

Then run:

source ~/.zshrc

After this, you can just use flutter instead of ~/Projects/flutter/bin/flutter.