Manifest Merger Failed: Causes and Solutions for Android Build Errors

What Does the "Manifest Merger Failed" Error Mean

The Manifest merger failed error is a critical build-time error in Android projects that stops the generation process for the final AndroidManifest.xml file for your application. It occurs when the Manifest Merger system detects an unresolvable conflict between elements from different sources: your main manifest (src/main/AndroidManifest.xml), manifests from library modules (.aar), product flavors, or build types.

A typical full error message looks like this:

Error: Manifest merger failed : 
Attribute application@label value=(@string/app_name) from AndroidManifest.xml:... is also present at 
AndroidManifest.xml:... value=(@string/other_name) 
Suggestion: add 'tools:replace="android:label"' to <application> element at AndroidManifest.xml:... to override

The conflict can involve any attributes: android:icon, android:label, activity#name, uses-permission, meta-data, and others.

Causes of the Error

The error is caused by the strict rules for merging XML documents. The main causes are:

1. Duplicate element with the same name. Two or more libraries/modules declare an <activity>, <service>, or <provider> with the same android:name attribute.
2. Conflicting attribute values. The same attribute (e.g., android:allowBackup on <application>) has different values in different manifests.
3. Incompatible applicationId. In a multi-module project, different modules may claim the primary package.
4. Permission conflict (uses-permission). Two libraries request the same permission with different maxSdkVersion or android:required levels.
5. Repeated component declaration. Your manifest already contains an <activity> that a linked AAR library (e.g., Firebase, Google Play Services) adds.

Solutions

Method 1: Using tools:replace (Primary Method)

This is the most common and precise method. You explicitly tell the merger which attribute from your manifest has priority.

1. Identify the conflicting attribute from the full error message (e.g., android:label).
2. Open your main AndroidManifest.xml (usually app/src/main/AndroidManifest.xml).
3. Find the element causing the conflict (most often <application> or a specific <activity>).
4. Add the tools namespace to the root <manifest> element if it's not already there:

   <manifest xmlns:android="http://schemas.android.com/apk/res/android"
             xmlns:tools="http://schemas.android.com/tools"
             package="com.example.app">
   

5. Add the tools:replace attribute to the conflicting element, listing all conflicting attributes separated by commas:

   <application
       android:label="@string/app_name"
       android:icon="@mipmap/ic_launcher"
       tools:replace="android:label, android:icon">
       ...
   </application>
   

6. Perform a clean build: Build -> Clean Project, then Build -> Rebuild Project.

Method 2: Removing the Conflicting Element (tools:node='remove')

If an element from a library is not needed (e.g., an unnecessary activity or permission), you can completely remove it from the final manifest.

1. Identify the full path and name of the element to remove (from the error).
2. In your manifest, declare that same element with the tools:node='remove' attribute:

   <!-- Remove the activity added by the 'com.example.unwanted:lib' library -->
   <activity
       android:name="com.example.unwanted.SomeActivity"
       tools:node="remove" />
   

   Important: android:name must exactly match what is shown in the error.

Method 3: Configuring Dependencies in Gradle

Sometimes the conflict arises because Gradle pulls in different versions of the same library.

1. Open the build.gradle file for the app module.
2. Find the dependencies section.
3. Force a specific version for the problematic library, using implementation with a version or resolutionStrategy:

   dependencies {
       // Explicitly specify a single version
       implementation 'com.google.android.material:material:1.12.0'
       // Or use 'force' for all dependencies
       configurations.all {
           resolutionStrategy {
               force 'com.some.library:conflicting-lib:1.2.3'
           }
       }
   }
   

4. Sync the project (click the 'Sync Now' button in the Gradle bar).

Method 4: Deep Analysis with gradle Command

For complex cases where the error doesn't point to a specific file, use detailed logging.

1. Run the build with maximum verbosity from the terminal (in the project root):

   ./gradlew assembleDebug --info --stacktrace
   

2. Search the output for the Merging manifest or Manifest merger block. It will list all manifest files being processed.
3. Find the two files that define the same element. These are typically your module's AndroidManifest.xml and files from build/intermediates/merged_manifests/... or .aar files in build/.
4. Manually fix the conflict using Methods 1 or 2.

Prevention

• Library versions. Keep dependencies up-to-date and compatible. Use ./gradlew dependencies to analyze the dependency tree.
• Project structure. Avoid duplicating <application> attributes in different build.gradle files (flavors/build-types). Move common attributes to the main manifest.
• Custom permissions. When adding a uses-permission, check if it's already declared by your libraries.
• Component naming. For your own Activity, Service, Receiver, use fully qualified names (with package) or unique names to minimize collision risk.
• Regular clean builds. Periodically run Build -> Clean Project, especially after major dependency changes.

Frequently Asked Questions (FAQ)

❓ The conflict is caused by a library that isn't in my dependencies. What should I do?

Sometimes a transitive dependency is pulled in through another library. Find the source using ./gradlew :app:dependencies and use exclude:

implementation('com.some:library:1.0') {
    exclude group: 'com.conflicting', module: 'bad-lib'
}

❓ Error: Attribute meta-data#android.support.VERSION value=... already defined. How to fix?

This is a classic conflict between support library versions (AndroidX). Ensure all libraries use the same version of androidx.*:androidx.*:1.0.0 or com.android.support:appcompat-v7:28.0.0. Enable android.useAndroidX=true and android.enableJetifier=true in gradle.properties.

❓ Manifest merger failed with a flavor (flavor). Where should I look?

The conflict may be between the main manifest and a specific flavor's manifest (e.g., src/free/AndroidManifest.xml). Check both. The solution is to move common elements to main and keep flavor-specific items in the flavor's manifest, using tools:replace if necessary.

❓ The error persists after I fix it. Why?

1. Gradle cache. Perform File -> Invalidate Caches and Restart... in Android Studio.
2. Wrong source set. Ensure you edited the manifest in the correct sourceSet (main, debug, flavorName).
3. A second conflict. There might be another conflict. Carefully read the entire error stack to the end.