Debugging native mobile apps on a physical device is essential for testing features that rely on real hardware, sensors, or network conditions that simulators cannot replicate. This guide walks you through the setup and workflow for both Android and iOS, covering everything from enabling developer options to inspecting network traffic and UI hierarchies.
What You’ll Need
- A physical Android or iOS device with a USB cable (or Wi-Fi for wireless debugging)
- A computer with Android Studio (for Android) or Xcode (for iOS) installed
- The app’s source code and build configuration
- For iOS: an Apple Developer account (free or paid) to run the app on a device
- For Android: USB debugging enabled in Developer Options
- Optional: a USB hub or adapter if your computer lacks the right port
Step-by-Step
- Enable Developer Options on Android: Go to Settings > About phone and tap Build number seven times. You’ll see a message that you are now a developer. Then go to Settings > Developer options and enable USB debugging.
- Enable Developer Mode on iOS: Go to Settings > Privacy & Security > Developer Mode and toggle it on. You’ll need to restart the device. (This appears after you’ve built an app to the device at least once.)
- Connect your device to the computer: Use a USB cable. On Android, you’ll see a prompt asking to allow USB debugging—check “Always allow” and tap OK. On iOS, trust the computer when prompted.
- Verify the device is detected:
- Android: In Android Studio, open the Device Manager (or look at the toolbar). Your device should appear. Alternatively, run
adb devicesin a terminal—if it shows “unauthorized,” check the phone screen. - iOS: In Xcode, go to Window > Devices and Simulators. Your device should be listed under “Devices.”
- Android: In Android Studio, open the Device Manager (or look at the toolbar). Your device should appear. Alternatively, run
- Build and run the app on the device:
- Android: In Android Studio, select your device from the dropdown and click Run. The app installs and launches.
- iOS: In Xcode, select your device as the scheme destination and click Run. You may need to set your signing team under Signing & Capabilities—choose your personal team if you don’t have a paid account.
- Start a debugging session: Both IDEs will attach a debugger automatically when you run the app. You can set breakpoints in your code and they will be hit on the device just like on a simulator.
- Use Logcat (Android) or Console (iOS):
- Android: Open the Logcat window in Android Studio. Filter by your app’s package name to see only its logs. Use
Log.d(),Log.e(), etc., in your code. - iOS: Open the Console app on your Mac (or use the Xcode debug area). You can filter by the device and process name. Use
print()orNSLog().
- Android: Open the Logcat window in Android Studio. Filter by your app’s package name to see only its logs. Use
- Inspect the UI hierarchy:
- Android: Use Layout Inspector in Android Studio (Tools > Layout Inspector) to see the view tree, properties, and even screenshot the live UI.
- iOS: Use Xcode’s View Debugging—click the “Debug View Hierarchy” button in the debug bar to see a 3D representation of your views.
- Debug network requests:
- Android: Use the Network Inspector in Android Studio (View > Tool Windows > Network Inspector) to see all HTTP/HTTPS traffic from your app.
- iOS: Use the Network tab in Xcode’s debug navigator, or use a proxy tool like Charles or Proxyman to inspect requests.
- Test with real device features: Use the device’s camera, GPS, or push notifications. For location, you can simulate a GPS location in the IDE (Android Studio: Extended Controls; Xcode: Simulate Location).
- Wireless debugging (optional):
- Android: After connecting via USB, run
adb tcpip 5555, then disconnect and runadb connect <device-ip>:5555. Or use the “Wireless debugging” option in Developer options (Android 11+). - iOS: Xcode supports wireless debugging via the Devices window—check “Connect via network” on your device.
- Android: After connecting via USB, run
- Use breakpoints efficiently: Set conditional breakpoints, log breakpoints (Android Studio), or add exception breakpoints to catch crashes.
- Monitor memory and CPU: Use the Profiler in Android Studio or the Instruments tool in Xcode to detect leaks or performance bottlenecks.
Common Mistakes
- Forgetting to enable Developer Mode on iOS: If you don’t see the Developer Mode toggle, build and run the app once—it will appear.
- USB debugging not authorized: Always check the phone screen for the authorization prompt; if you missed it, run
adb kill-serverandadb start-serverto reset. - Using the wrong signing team on iOS: A free personal team only allows 7 days of provisioning; you’ll need to re-run the build after that.
- Not filtering Logcat: Without a filter, you’ll see system logs and miss your app’s messages.
- Assuming the simulator is enough: Many bugs only appear on real hardware (e.g., low memory, thermal throttling, network latency).
Tips
- Use a dedicated test device: Keep a device with a known OS version for reproducible tests.
- Set up a clean network: Use a proxy to inspect HTTPS traffic—install the proxy’s CA certificate on the device to decrypt SSL.
- Automate with scripts: Use
adbcommands to automate repetitive tasks like installing builds or clearing app data. - Keep the device charged: Debugging drains battery; use a powered USB hub.
- Use crash reporting tools: Integrate a crash reporter (like Firebase Crashlytics or Sentry) to get stack traces from real users, but for development, the IDE’s crash logs are sufficient.
Troubleshooting
- Device not detected:
- Android: Try a different USB cable (many cables are charge-only). Reinstall the USB driver (on Windows). Run
adb kill-serverandadb start-server. - iOS: Unlock the device and tap “Trust” on the prompt. Restart both the computer and device. Check that Xcode is up to date.
- Android: Try a different USB cable (many cables are charge-only). Reinstall the USB driver (on Windows). Run
- App crashes on launch: Check the crash log in Logcat or Console. Look for missing permissions, or an architecture mismatch (e.g., building for x86 but the device is ARM).
- Breakpoints not hitting: Ensure the build is a debug build (not release). Also check that the code being executed is the same as the source—clean and rebuild.
- Network Inspector shows no traffic: On Android, ensure your app uses HTTP/HTTPS libraries that are compatible (e.g., OkHttp). On iOS, the Network tab may only show active connections; use a proxy for full visibility.
- Slow debugging: Disable breakpoints that are not needed, and use a wired connection instead of Wi-Fi for better speed.
- iOS “Could not find Developer Disk Image”: This means your Xcode version is older than the iOS version on the device. Update Xcode.
Frequently Asked Questions
Do I need a paid Apple Developer account to debug on a real iPhone?
No. A free personal team account allows you to run your app on a device for 7 days at a time. After that, you simply rebuild and reinstall.
Can I debug an Android app wirelessly without root?
Yes. With Android 11 and above, you can use the built-in Wireless debugging option. For older versions, you can use adb tcpip after a USB connection.
Why does my app work on the simulator but crash on the device?
Simulators share the host machine’s resources (CPU, memory) and don’t have the same hardware constraints. On a real device, you may encounter memory pressure, missing sensors, or different screen sizes that expose bugs.
How do I inspect the UI of a React Native or Flutter app on a device?
For React Native, you can use the built-in dev menu (shake the device) and select “Show Inspector.” For Flutter, use the Flutter Inspector in Android Studio or VS Code. Both work on physical devices.
Can I debug push notifications on a real device?
Yes, that’s the best way. For iOS, you need a valid APNs token and a real device to receive notifications. For Android, you can use Firebase Cloud Messaging with the device’s token.
What is the difference between Logcat and Android Studio’s Logcat window?
Logcat is the system-wide logging service on Android. The Logcat window in Android Studio is a viewer that lets you filter and search those logs. It’s the same data, just a better interface.
Related
General steps for current mainstream versions; menus can differ by device and version. See the disclaimer or report an error.
More in this bed
- How to Create App Shortcuts in Windows 10 Start Menu
- How to Rename a SQL Server Database
- Fix Google Calendar Not Syncing on iPhone
- Fix Skype Microphone Not Working on Windows
- Google Docs Landscape: Change Page Orientation
- Recover Deleted Admin Account in Windows 11