Fix: React Native Android Build Failed

The Error

Running npx react-native run-android or building with Gradle fails:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:compileDebugJavaWithJavac'.
> error: package com.facebook.react does not exist

Or an SDK version error:

FAILURE: Build failed with an exception.

* What went wrong:
A problem occurred configuring project ':app'.
> Failed to find target with hash string 'android-34' in: /usr/local/lib/android/sdk

Or a duplicate module error:

error: duplicate files copied in APK META-INF/...
  File 1: /path/to/.gradle/...
  File 2: /path/to/.gradle/...

Or after upgrading React Native:

Invariant Violation: "main" has not been registered.
This can happen if:
* Metro (the local dev server) is run from the wrong folder.
* A module failed to load due to an error and `AppRegistry.registerComponent` wasn't called.

Why This Happens

React Native Android builds involve multiple layers — the React Native framework, Gradle build system, Android SDK, and your JavaScript bundle — each of which can fail independently:

• Android SDK target version not installed — the compileSdkVersion or targetSdkVersion in build.gradle specifies an SDK version that isn’t installed in your Android SDK.
• Gradle wrapper version mismatch — the Gradle version in gradle-wrapper.properties is incompatible with the Android Gradle Plugin (AGP) version.
• Java version mismatch — React Native 0.71+ requires Java 11+. Older versions may conflict with newer Java.
• Duplicate dependencies — two different packages include the same library at different versions. Gradle fails to resolve the conflict.
• Metro bundler not running — run-android tries to connect to Metro on port 8081, but Metro isn’t running or is running on the wrong port.
• CMake/NDK issues — native modules that require C++ compilation fail if NDK or CMake isn’t installed or is the wrong version.
• node_modules out of sync — after upgrading React Native or adding packages, the native code in node_modules doesn’t match what was compiled.

Fix 1: Install the Required Android SDK Version

The error “Failed to find target with hash string ‘android-34’” means the SDK version specified in build.gradle isn’t installed:

# Check what's installed
sdkmanager --list | grep "platforms;android"

# Install the required version (e.g., android-34)
sdkmanager "platforms;android-34"
sdkmanager "build-tools;34.0.0"

Or install via Android Studio:

1. Open Android Studio → SDK Manager (Tools → SDK Manager)
2. SDK Platforms tab → check the version your project requires
3. SDK Tools tab → ensure “Android SDK Build-Tools” is installed for that version

Check which version your project needs:

// android/build.gradle
ext {
    compileSdkVersion = 34    // This version must be installed
    targetSdkVersion = 34
    minSdkVersion = 21
    buildToolsVersion = "34.0.0"
}

Fix 2: Fix Gradle and Java Version Issues

React Native 0.73+ requires Java 17. Check your Java version and Gradle compatibility:

# Check Java version
java -version
# java version "17.0.x" or "11.0.x"

# Check JAVA_HOME
echo $JAVA_HOME

# Set JAVA_HOME if needed (macOS with Homebrew Java 17)
export JAVA_HOME=$(/usr/libexec/java_home -v 17)

Common compatibility matrix:

Update Gradle wrapper version:

# android/gradle/wrapper/gradle-wrapper.properties
distributionUrl=https\://services.gradle.org/distributions/gradle-8.3-all.zip

Update Android Gradle Plugin in android/build.gradle:

buildscript {
    dependencies {
        classpath("com.android.tools.build:gradle:8.1.4")  // Match your Gradle version
    }
}

Fix 3: Clean Build Artifacts

Stale build cache causes many unexplained failures. Clean everything and rebuild:

# Clean React Native build
cd android
./gradlew clean
cd ..

# Clear Metro bundler cache
npx react-native start --reset-cache

# Clear watchman cache (if installed)
watchman watch-del-all

# Remove node_modules and reinstall
rm -rf node_modules
npm install
# or
yarn install

# For iOS too (if needed)
cd ios && pod install && cd ..

One-liner for a full reset:

cd android && ./gradlew clean && cd .. && \
  rm -rf node_modules android/.gradle && \
  npm install && \
  cd android && ./gradlew assembleDebug

Fix 4: Fix Duplicate Module/File Errors

When two dependencies include the same file, the APK packer fails:

Duplicate files copied in APK META-INF/DEPENDENCIES
  File 1: ...
  File 2: ...

Fix in android/app/build.gradle:

android {
    packagingOptions {
        // Exclude duplicate meta-info files
        exclude 'META-INF/DEPENDENCIES'
        exclude 'META-INF/LICENSE'
        exclude 'META-INF/LICENSE.txt'
        exclude 'META-INF/NOTICE'
        exclude 'META-INF/NOTICE.txt'
        exclude 'META-INF/*.kotlin_module'
    }
}

For duplicate native library (.so) files:

android {
    packagingOptions {
        pickFirst 'lib/x86/libc++_shared.so'
        pickFirst 'lib/x86_64/libc++_shared.so'
        pickFirst 'lib/armeabi-v7a/libc++_shared.so'
        pickFirst 'lib/arm64-v8a/libc++_shared.so'
    }
}

Fix 5: Fix Metro Bundler Connection Issues

run-android connects to Metro at localhost:8081 to load the JS bundle. If Metro isn’t running or the device can’t reach it:

Start Metro manually first:

# Terminal 1 — start Metro
npx react-native start

# Terminal 2 — build and run the app
npx react-native run-android

For physical Android devices, the device needs to reach your development machine’s Metro server:

# Forward port 8081 from device to your machine
adb reverse tcp:8081 tcp:8081

# Then run the app
npx react-native run-android

Check Metro is running:

curl http://localhost:8081/status
# Should return: {"status":"packager-status:running"}

If Metro crashes or shows module errors, clear the cache:

npx react-native start --reset-cache

Fix 6: Fix “has not been registered” Error

This error means the app started but the JS bundle failed to load or the component wasn’t registered:

// WRONG — component name must match exactly what's in index.js
AppRegistry.registerComponent('MyApp', () => App);

// index.js — the registered name must match the app name in app.json
AppRegistry.registerComponent(appName, () => App);

// app.json
{
  "name": "MyApp",   // Must match the first arg of registerComponent
  "displayName": "My App"
}

If the bundle loads but a module fails:

# Check Metro output for the specific error
npx react-native start 2>&1 | grep -i error

# Try loading the bundle directly in a browser
curl http://localhost:8081/index.bundle?platform=android

Fix 7: Fix NDK and Native Module Build Errors

If a package requires native code compilation:

Error: NDK at /path/to/sdk/ndk was not found.
No version of NDK matched the requested version

Install NDK via Android Studio:

1. SDK Manager → SDK Tools → NDK (Side by side) → Install
2. Note the installed version (e.g., 25.2.9519653)

Specify NDK version in android/build.gradle:

android {
    ndkVersion "25.2.9519653"   // Match what you installed
}

Or in android/local.properties:

ndk.dir=/path/to/sdk/ndk/25.2.9519653

For CMake not found:

sdkmanager "cmake;3.22.1"

Still Not Working?

Check the full Gradle error output:

cd android
./gradlew assembleDebug --stacktrace --info 2>&1 | tail -100
# --stacktrace shows the full Java stack trace
# --info shows verbose Gradle output

Check for conflicting React Native versions:

# See what version is installed
cat node_modules/react-native/package.json | grep '"version"'

# Check for multiple React versions (should be one)
npm ls react

Verify Android SDK path:

# android/local.properties must point to your SDK
cat android/local.properties
# sdk.dir=/Users/you/Library/Android/sdk  (macOS)
# sdk.dir=C\:\\Users\\you\\AppData\\Local\\Android\\Sdk  (Windows)

If local.properties is missing, create it or let Android Studio create it by opening the android/ folder as a project.

Run on an emulator vs physical device. Some build issues are device-specific. If a physical device fails, try an emulator, and vice versa.

For related React Native issues, see Fix: React Native Metro Bundler Failed and Fix: Xcode Build Failed.