react-native run-android stops with 'gradlew installDebug' failed
react-native run-android ends at the installDebug step on WindowsShort answer
That line only says the Gradle task behind run-android failed. The reason is in the Gradle output, so run the same task by hand with a stack trace and read the first error. Four causes cover most cases: a stuck adb server, no emulator or phone online, a JDK newer than 17, or a missing ANDROID_HOME.
Fix it fast
1Find out which cause you have
react-native run-android runs the installDebug Gradle task by default and prints only a short wrapper message. Run that task yourself from the android folder with a stack trace. The first line that starts with a cause or an error names the real problem.
cd android gradlew.bat app:installDebug --stacktrace2Match what you see, then jump to its fix
- 1
Execution failed for task ':app:installDebug' with com.android.ddmlib.ShellCommandUnresponsiveException in the cause.The adb server is stuckFix - 2
adb devices prints an empty list, or the device state is offline.No emulator or phone is onlineFix - 3
gradlew.bat -version shows a JVM above 17, and the Gradle output reports a Java or Gradle compatibility problem.The JDK is newer than the one React Native expectsFix - 4
adb is not recognized as a command, or echo %ANDROID_HOME% prints the variable name back instead of a folder.ANDROID_HOME is not set, so the SDK tools are not foundFix
- 1
What does the error look like?
react-native run-android ends at the installDebug step on WindowsExecution failed for task ':app:installDebug'.com.android.ddmlib.ShellCommandUnresponsiveException
Cause 1 of 4
The adb server is stuck
1Check
The React Native troubleshooting page lists this exact exception and says to restart the adb server. Ask adb what it sees first.
adb devices -l2Fix
Stop the adb server and start it again, then run the app again.
adb kill-server
adb start-server3Verify
adb devices lists your emulator or phone as device, and the install runs.
adb devices
npx react-native run-androidConfirmed by reactnative.dev
Cause 2 of 4
No emulator or phone is online
1Check
adb reports a state for each device. offline means it is not connected or not responding, and no device means nothing is attached. The state device is the normal working one. A just-started emulator can also be missing from the list if it was started before the adb server.
adb devices -l2Fix
Start an emulator from the AVD Manager in Android Studio, or plug in a phone with a USB cable, with USB debugging switched on in its developer options. If a running emulator is missing from the list, stop the adb server and start it again, then list the devices once more.
adb kill-server
adb start-server
adb devices3Verify
The device shows the state device in the list.
adb devices -lConfirmed by developer.android.com
Cause 3 of 4
The JDK is newer than the one React Native expects
1Check
The React Native setup guide recommends JDK 17 and warns of problems with higher versions. Gradle takes its JVM from JAVA_HOME, and org.gradle.java.home in gradle.properties wins over it for the build process.
cd android
gradlew.bat -version
echo %JAVA_HOME%
findstr "org.gradle.java.home" gradle.properties2Fix
Install JDK 17, point JAVA_HOME at it in the Windows environment variables, and remove or correct org.gradle.java.home if gradle.properties sets another one. Open a new Command Prompt afterwards so it reads the change.
:: current Command Prompt only; make it permanent in the Windows environment variables window
:: example path, use the folder of your own JDK 17
set JAVA_HOME=C:\Program Files\Java\jdk-173Verify
In a new Command Prompt, gradlew.bat -version reports a 17.x JVM.
cd android
gradlew.bat -versionConfirmed by reactnative.dev
Cause 4 of 4
ANDROID_HOME is not set, so the SDK tools are not found
1Check
The setup guide has Windows users create an ANDROID_HOME user variable and add the platform-tools folder to Path. By default the SDK is installed under %LOCALAPPDATA%\Android\Sdk.
echo %ANDROID_HOME%
adb devices2Fix
Create the ANDROID_HOME user variable with the SDK folder, add %LOCALAPPDATA%\Android\Sdk\platform-tools to Path, and open a new Command Prompt.
:: current Command Prompt only; make both permanent in the Windows environment variables window
set ANDROID_HOME=%LOCALAPPDATA%\Android\Sdk
set PATH=%PATH%;%LOCALAPPDATA%\Android\Sdk\platform-tools3Verify
In a new Command Prompt the variable prints a folder and adb devices runs.
echo %ANDROID_HOME%
adb devicesConfirmed by reactnative.dev
How do I stop it coming back?
- Keep one JDK 17 installation and point JAVA_HOME at it, so Gradle and Android Studio agree.
- Start the emulator before running the app, and run adb devices once to see it listed.
- Run gradlew.bat app:installDebug --stacktrace whenever run-android prints only the wrapper message.
- Set ANDROID_HOME and Path once per machine and check them again after reinstalling Android Studio.
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:
- QistLockA NestJS and React SaaS driving an Android Device Owner agent that locks financed phones when payments lapse.
- TaxiDexMy own multi-tenant taxi dispatch SaaS: API, dispatcher portal, driver and passenger apps, and the servers underneath.
- TaskvareA task and project-management suite: React on the web, Flutter on mobile, TypeScript underneath.
Related fixes
Mobile apps
Gradle cannot find the Android SDK on this machine
FAILURE: Build failed with an exception. What went wrong: SDK location not found.
Gradle looks for the Android SDK in the sdk.dir line of android/local.properties and in the ANDROID_HOME environment variable, and found neither.
4 causes, each with a fixMobile apps
Gradle ignores JAVA_HOME and starts a different JDK
Android Gradle plugin requires Java 17 to run. You are currently using Java 11.
Gradle does not read JAVA_HOME first.
3 causes, each with a fixMobile apps
Android build stops at processDebugManifest in a React Native app
Manifest merger failed
processDebugManifest is the step that merges your AndroidManifest.xml with the manifests of every library.
2 causes, each with a fixMobile apps
React Native Android build cannot find the foojay-resolver-convention plugin
Plugin [id: 'org.gradle.toolchains.foojay-resolver-convention'] was not found in any of the following sources:
The foojay plugin is a settings plugin that Gradle downloads from the Plugin Portal.
3 causes, each with a fixMobile apps
Kotlin and Java compile to different JVM targets in a React Native Android build
'compileJava' task (current target is 1.8) and 'compileKotlin' task (current target is 11)
Gradle refuses to build when the Java task and the Kotlin task target different JVM versions.
3 causes, each with a fixMobile apps
Gradle cannot run node in a React Native Android build
Process 'command 'node'' finished with non-zero exit value 1
The React Native Gradle plugin starts node for bundling.
3 causes, each with a fix