Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages
Flutter and app store releases

The app freezes on 'Waiting for Debugger' on the device

ErrorWaiting For Debugger

Short answer

The device is set to hold the selected app until a debugger attaches, and none did. Open Developer options, turn Wait for debugger off, then start the app again. If you want to debug, use the Attach Debugger button in Android Studio. A non-debuggable build cannot be debugged at all.

  • Applies to Android Studio current stable, Android 14 to 16, Android Gradle Plugin 8.x and 9.x
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Fix it fast

  1. 1Find out which cause you have

    Check whether the device lists your app as the debug app with Wait for debugger on, and whether adb sees the device.

    adb devices
  2. 2Match what you see, then jump to its fix

    1. 1The dialog appears on the phone every time the app starts, even when you run it from the launcherWait for debugger is turned on in Developer optionsFix
    2. 2The dialog shows after Run, and Android Studio never attachesThe run was not a debug run, or the build is not debuggableFix

What does the error look like?

  • Waiting For Debugger
  • Application X (process com.example.app) is waiting for the debugger to attach.

Cause 1 of 2

Wait for debugger is turned on in Developer options

1Check

Developer options has a Select debug app item. The Wait for debugger switch stays unavailable until an app is selected there. When both are set, that app waits for a debugger every time it runs.

adb shell am start -n com.example.app/.MainActivity

2Fix

On the device, open Settings > System > Developer options, turn Wait for debugger off, then force-stop and start the app again.

# on the device
Settings > System > Developer options > Wait for debugger (off)

3Verify

The app starts without the dialog.

adb shell am start -n com.example.app/.MainActivity

Confirmed by developer.android.com

Did this fix it?

Cause 2 of 2

The run was not a debug run, or the build is not debuggable

1Check

To debug, the build variant must be debuggable. The default debug variant is. Custom build types need isDebuggable = true.

grep -n "debuggable\|isDebuggable" app/build.gradle*

2Fix

Select a debug build variant, or add isDebuggable = true to the build type you debug. Then use Debug, or Run > Attach Debugger to Android Process.

android {
    buildTypes {
        create("staging") {
            isDebuggable = true
        }
    }
}

3Verify

The debugger attaches, and breakpoints in your code turn solid.

adb shell pm list packages com.example.app

Confirmed by developer.android.com

Did this fix it?

How do I stop it coming back?

  • Turn Wait for debugger off when you finish a debug session.
  • Keep debug work on the debug variant, and release builds non-debuggable.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Every cause above names the document that confirms it. I have not reproduced this fix on a machine of my own yet, so read it as documented guidance, not a test report. Found a mistake? Tell me.

Which stack is behind this page?

Projects of mine built on the same technologies:

Related fixes

Mobile apps

A phone is plugged in over USB but Android Studio and adb do not list it

adb devices prints List of devices attached with nothing below it

adb lists a phone only when four things hold: USB debugging is on, you accepted the computer's RSA key on the phone, the computer has a driver or udev rule for the device, and the cable carries data to a running adb server.

6 causes, each with a fix

Mobile apps

Android Studio cannot pair the phone over Wi-Fi

The Pair devices over Wi-Fi dialog lists no device

Wireless pairing needs the phone on Android 11 or higher and on the same Wi-Fi network as the computer, with current Platform-Tools.

4 causes, each with a fix

Next step

Want this handled for good?

I look after servers, apps and releases end to end. Tell me what keeps breaking.