Are you staring at a frustrating “Manifest merger failed with multiple errors” message in your Android development environment? You’re not alone. This error remains one of the most common yet perplexing issues Android developers face in 2025, especially as projects grow in complexity and incorporate multiple libraries and dependencies.
In this comprehensive guide, I’ll walk you through everything you need to know about manifest merger errors, from understanding the root causes to implementing both quick fixes and long-term solutions. Whether you’re a seasoned developer or just starting with Android development, this troubleshooting resource will help you resolve these errors efficiently and get your project back on track.
Android Manifest Merger Process
Before diving into solutions, let’s ensure we understand what’s actually happening during the manifest merger process that could lead to these errors.
What is AndroidManifest.xml?
The AndroidManifest.xml file is the heart of any Android application. It contains essential information about your app that the Android system needs before it can run any of your code. This includes:
- Package name and application ID
- App components (activities, services, broadcast receivers, content providers)
- Required permissions
- Hardware and software features required
- API level compatibility
- Library dependencies
Every Android application must have this file at the root of its project directory. However, the complexity arises when your app incorporates multiple libraries and modules, each with its own manifest file.
How Manifest Merging Works
The manifest merger process is an automated system where Android’s build tools combine all the manifest files from your app and its dependencies into one final AndroidManifest.xml file. This process follows these steps:
- Collects all manifest files from your app and its libraries
- Establishes a hierarchy of importance (your app’s manifest has highest priority)
- Attempts to merge declarations based on predefined rules
- Resolves conflicts according to specified strategies
- Produces a single, unified manifest for your application
In an ideal scenario, this happens seamlessly in the background. But when conflicts arise that the merger can’t resolve automatically, you’ll encounter the dreaded “manifest merger failed” error.
Common Reasons for Merger Failures
Understanding the typical causes helps narrow down your troubleshooting efforts:
- Conflicting attribute values: Two or more manifests define the same attribute with different values
- Duplicate declarations: Multiple components declared with the same name
- Incompatible permission requirements: Libraries requesting conflicting permissions
- SDK version mismatches: Different minimum or target SDK versions
- Plugin compatibility issues: Especially common with newer Gradle or AGP versions
As of 2025, with Android development moving toward more modular approaches and microservice architectures, these conflicts have become even more common.
Identifying Manifest Merger Error Types
The first step in resolving manifest merger errors is identifying exactly what type of conflict you’re dealing with. Let’s look at the main categories:
Attribute Conflicts
Attribute conflicts occur when the same attribute is defined differently in multiple manifest files. For example:
<!-- In your app's manifest -->
<activity android:name=".MainActivity" android:screenOrientation="portrait" />
<!-- In a library's manifest -->
<activity android:name=".MainActivity" android:screenOrientation="landscape" />
In this case, the merger doesn’t know which screenOrientation value to use.
Element Conflicts
Element conflicts happen when similar elements (like activities, services, or receivers) are declared in multiple places with conflicting configurations:
<!-- Your manifest -->
<service android:name=".MyService" android:enabled="true" />
<!-- Library manifest -->
<service android:name=".MyService" android:enabled="false" />
Package Name Issues
Package name conflicts are particularly tricky. They often occur when:
- Multiple libraries use the same package name
- A library’s package name conflicts with your app’s package name
- Package name declarations are inconsistent across different build variants
Version Code Conflicts
Different components might require different minimum SDK versions or target SDK versions:
<!-- Your manifest -->
<uses-sdk android:minSdkVersion="24" android:targetSdkVersion="34" />
<!-- Library manifest -->
<uses-sdk android:minSdkVersion="26" />
Step-by-Step Troubleshooting Approach
Now that we understand the types of errors, let’s establish a systematic approach to identify and fix them.
Reading Error Logs Effectively
The error message might look intimidating, but it contains valuable information. Here’s how to decode it:
- Look for the phrase “Manifest merger failed” followed by specific error details
- Identify the conflicting elements or attributes
- Note the file paths mentioned in the error
- Check for suggestions in the error message itself
A typical error message might look like:
Manifest merger failed : Attribute application@appComponentFactory value=(android.support.v4.app.CoreComponentFactory) from [com.android.support:support-compat:28.0.0]
AndroidManifest.xml:22:18-91
is also present at [androidx.core:core:1.0.0] AndroidManifest.xml:22:18-86 value=(androidx.core.app.CoreComponentFactory).
This tells us there’s a conflict with the appComponentFactory
attribute between support library and AndroidX components.
Using the Gradle –info Flag
For more detailed information, run your build with the --info
flag:
./gradlew assembleDebug --info
This provides verbose output about the merger process, showing you exactly which files are being merged and where conflicts occur.
Advanced Debug Techniques
For particularly stubborn issues, you can enable manifest merger reports:
android {
buildFeatures {
manifestMergerReport true
}
}
This generates detailed reports in your project’s build/outputs/logs/manifest-merger-debug-report.txt
file, showing the entire merger process.
Resolving Common Manifest Merger Errors
Now let’s address specific solutions for the most common manifest merger errors.
Handling Library Dependency Conflicts
Library conflicts are the most frequent cause of manifest merger errors. Here’s how to address them:
- Identify conflicting libraries: Look for libraries that might be included multiple times or in different versions
- Use the exclude keyword: Remove transitive dependencies that cause conflicts:
implementation('com.example:library:1.0.0') {
exclude group: 'com.google.firebase', module: 'firebase-core'
}
- Force consistent versions: Ensure all parts of your project use consistent library versions:
configurations.all {
resolutionStrategy {
force 'androidx.core:core:1.10.0'
force 'androidx.appcompat:appcompat:1.6.1'
}
}
- Use the dependency insight task to identify the dependency tree:
./gradlew app:dependencyInsight --dependency androidx.core:core
Fixing Permission Conflicts
Permission conflicts occur when libraries request permissions that conflict with each other or with your app’s requirements:
- Use tools:remove: Remove unwanted permissions from libraries:
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<uses-permission android:name="android.permission.CAMERA"
tools:node="remove" />
</manifest>
- Use tools:replace: Override a library’s permission:
<uses-permission android:name="android.permission.INTERNET"
tools:node="replace" />
Resolving Activity and Service Declarations
Activity and service conflicts can be handled with similar approaches:
- Use tools:node=”replace” to override library declarations:
<activity
android:name=".MainActivity"
android:exported="true"
tools:node="replace">
<intent-filter>
<action android:name="android.intent.action.MAIN" />
<category android:name="android.intent.category.LAUNCHER" />
</intent-filter>
</activity>
- Use tools:node=”merge” to combine attributes while keeping yours as priority:
<activity
android:name=".SplashActivity"
android:theme="@style/SplashTheme"
tools:node="merge">
</activity>
Tools to Automate Conflict Resolution
Several tools have emerged in 2025 to help manage manifest conflicts:
Tool | Purpose | Best Used For |
---|---|---|
Manifest Merger Plugin | Visualizes conflicts | Large projects with many libraries |
Dependency Analyzer | Maps dependency relationships | Identifying root causes of conflicts |
Gradle Doctor | Detects common build issues | General build optimizations |
AndroidX Migration Assistant | Helps with legacy to AndroidX migration | Projects transitioning to AndroidX |
Advanced Solutions for Complex Manifest Merger Issues
When simple fixes don’t work, you may need more sophisticated approaches.
Using Manifest Placeholders
Manifest placeholders allow you to parameterize your manifest and provide values at build time:
<!-- In AndroidManifest.xml -->
<activity android:name="${activityName}" />
// In build.gradle
android {
defaultConfig {
manifestPlaceholders = [activityName: ".MainActivity"]
}
buildTypes {
debug {
manifestPlaceholders = [activityName: ".DebugActivity"]
}
}
}
This is particularly useful for build variant-specific configurations.
Implementing Custom Merger Rules
For complex scenarios, you can create a custom manifest merger file:
<!-- In app/src/main/AndroidManifest.xml -->
<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android"
xmlns:tools="http://schemas.android.com/tools">
<!-- Custom merger rule file reference -->
<merge tools:custom-merger-file="manifests/custom-manifest-merger.xml"/>
<!-- Rest of your manifest -->
</manifest>
Then define your custom rules in the referenced file.
When to Use tools:replace and tools:remove
Understanding when to use each tools namespace attribute is crucial:
- tools:node=”replace”: Completely replaces an element from a lower-priority manifest
- tools:node=”remove”: Removes an element from the final merged manifest
- tools:node=”merge”: Combines attributes, with your manifest taking precedence
- tools:node=”merge-only-attributes”: Merges only attributes, not child elements
- tools:replace=”attr1,attr2″: Replaces specific attributes rather than the whole element
Here’s a more concrete example:
<application
android:allowBackup="true"
android:icon="@mipmap/ic_launcher"
android:roundIcon="@mipmap/ic_launcher_round"
android:label="@string/app_name"
tools:replace="android:icon,android:label"
tools:node="merge">
</application>
In this case, we’re replacing only the icon and label attributes while merging the rest.
Preventing Manifest Merger Errors in Future Projects
An ounce of prevention is worth a pound of cure. Here are strategies to minimize manifest merger errors in your future projects:
- Maintain consistent dependency versions: Use a centralized dependency management approach with version catalogs (introduced in Gradle 7.0)
// In settings.gradle
dependencyResolutionManagement {
versionCatalogs {
libs {
version('androidx-core', '1.10.0')
library('androidx-core', 'androidx.core', 'core').versionRef('androidx-core')
}
}
}
- Regularly audit your dependencies: Use the Gradle dependency insight task to identify and remove unnecessary or duplicate dependencies
- Use dynamic feature modules: Isolate functionalities to minimize manifest conflicts
- Document library requirements: Maintain documentation about each library’s manifest requirements to anticipate potential conflicts
- Implement continuous integration checks: Set up CI processes that fail builds when manifest merger issues are detected
- Consider manifest-only modules: Create specialized modules that only contain manifest configurations for complex cases
Here’s a visualization of an effective dependency management strategy:
Level | Strategy | Implementation |
---|---|---|
Project | Version catalogs | Centralized version definitions |
Module | Explicit dependencies | Clear implementation vs api dependencies |
CI | Validation checks | Automated detection of conflicts |
Documentation | Requirements tracking | Document each library’s manifest needs |
Conclusion
Manifest merger errors can be frustrating, but with the systematic approach outlined in this guide, you’ll be well-equipped to diagnose and resolve them efficiently. Remember that the key to success lies in understanding the merger process, carefully reading error messages, and applying the appropriate resolution strategy.
As Android development continues to evolve in 2025, staying on top of best practices for manifest management will save you countless hours of debugging and keep your development process smooth. By implementing preventive measures and using the troubleshooting techniques covered here, you can turn manifest merger errors from a major roadblock into a minor inconvenience.
Remember: most manifest merger issues stem from dependency conflicts or inconsistent configurations. A methodical approach focused on identifying the specific conflict type will lead you to the right solution much faster than trial-and-error fixes.
Frequently Asked Questions
What’s the difference between tools:node=”replace” and tools:replace=”attribute”?
tools:node=”replace” replaces an entire XML element from a library manifest with your version, while tools:replace=”attribute” only replaces specific attributes within an element while preserving others. Use the latter when you only need to change certain properties but want to keep the rest intact.
How do I resolve manifest merger errors related to Firebase libraries?
Firebase-related manifest merger errors often occur due to version mismatches between different Firebase components. The best approach is to use the Firebase BoM (Bill of Materials) to ensure consistent versions:
implementation platform('com.google.firebase:firebase-bom:32.7.0')
implementation 'com.google.firebase:firebase-analytics'
implementation 'com.google.firebase:firebase-auth'
This ensures all Firebase components use compatible versions without specifying individual version numbers.
Can manifest merger errors occur in release builds but not debug builds?
Yes, this can happen when you have build-variant specific configurations or dependencies. Check for differences in your buildTypes
blocks and make sure your productFlavors
don’t introduce conflicting manifest elements. Using manifest placeholders with variant-specific values can help resolve these issues.
How do I fix “Manifest merger failed: Apps targeting Android 13+ (version 33+)” errors?
For Android 13+ targeting apps, you’ll often encounter issues related to notification permissions and other new requirements. Make sure to:
- Add the POST_NOTIFICATIONS permission if you’re using notifications
- Set android:exported=”true” for components that need to be accessible by other apps
- Specify android:enableOnBackInvokedCallback=”true” when using predictive back gestures
What should I do when manifest merger errors occur after updating Gradle or the Android Gradle Plugin?
After upgrading build tools, manifest merger errors often appear due to changed behaviors. Try these steps:
- Clear your project cache:
./gradlew cleanBuildCache
- Invalidate caches in Android Studio
- Check if there are compatibility issues between your plugins and the new Gradle version
- Look for deprecated manifest entries that might now cause conflicts
- Consider a gradual upgrade approach by updating one component at a time