Introduction

The Gradle error about com.android.support versions means your dependency graph contains support-library artifacts from different releases. Android support libraries were published as a coordinated set, so mixing versions usually breaks resource merging, binary compatibility, or both.

Why the Versions Must Match

Older Android projects often depend on artifacts such as appcompat-v7, design, cardview-v7, and recyclerview-v7. Those packages were versioned together. If one library is on 28.0.0 and another transitively pulls in 27.1.1, Gradle flags the mismatch because the classes and resources were designed to ship in lockstep.

A minimal bad example looks like this:

1dependencies {
2    implementation 'com.android.support:appcompat-v7:28.0.0'
3    implementation 'com.android.support:recyclerview-v7:27.1.1'
4}

This usually produces the familiar build failure before compilation finishes. The error is useful because the alternative would be a less obvious runtime or resource-linking problem.

Fix the Direct Dependencies First

The first step is to align every support-library dependency to the same version. For projects still on support libraries, 28.0.0 is usually the final target release.

1dependencies {
2    implementation 'com.android.support:appcompat-v7:28.0.0'
3    implementation 'com.android.support:recyclerview-v7:28.0.0'
4    implementation 'com.android.support:design:28.0.0'
5    implementation 'com.android.support:cardview-v7:28.0.0'
6}

If the build still fails after that change, the mismatch is probably coming from a transitive dependency rather than from a line you wrote directly.

Find the Real Source of the Mismatch

The next step is to inspect the dependency graph instead of guessing.

./gradlew app:dependencies

Search the output for com.android.support. You are looking for a library that drags in a different version transitively. A common example is an older third-party package built against a previous support-library release.

Once you identify the dependency, you have three main options:

1. Upgrade the third-party library to a version that matches your support-library baseline.
2. Exclude the older support artifact and declare the correct one yourself.
3. Replace the dependency if it is abandoned.

A targeted exclusion looks like this:

1dependencies {
2    implementation('com.example:legacy-widget:1.4.0') {
3        exclude group: 'com.android.support', module: 'support-v4'
4    }
5
6    implementation 'com.android.support:support-v4:28.0.0'
7}

Use exclusions carefully. They are safe only when the remaining dependency is actually compatible with the library you are keeping.

Why AndroidX Is the Long-Term Answer

If you are maintaining an older codebase, support-library alignment fixes the immediate build. It does not solve the larger problem that com.android.support is legacy infrastructure. AndroidX replaced it with clearer package names and ongoing maintenance.

A typical migration uses these Gradle properties:

android.useAndroidX=true
android.enableJetifier=true

Then you run the Android Studio refactor to migrate package references. That is usually a better investment than repeatedly patching support-library conflicts, especially if the project still receives feature work.

A Practical Debugging Workflow

When this error appears, use a fixed sequence:

1. Align all direct support-library declarations.
2. Run ./gradlew app:dependencies.
3. Identify any transitive library that still references a different support version.
4. Upgrade, exclude, or replace that library.
5. Consider AndroidX migration if the project is still active.

That workflow is faster than trying random Gradle snippets from search results. Dependency problems are graph problems, so you need to inspect the graph.

Common Pitfalls

• Updating only one support artifact and assuming Gradle will harmonize the rest automatically. It will not when conflicting versions are explicit.
• Forgetting about transitive dependencies. The mismatch often comes from a third-party library, not from your own build.gradle lines.
• Using broad exclusions without checking compatibility. That can hide one error and create a new runtime failure.
• Mixing AndroidX and old support packages in the same unresolved configuration. Migration must be deliberate.
• Treating this as a compiler quirk instead of a dependency-management problem. The build is telling you the graph is inconsistent.

Summary

• All com.android.support artifacts in one build must use the same version.
• Start by aligning direct dependencies, usually to 28.0.0 in legacy projects.
• Use ./gradlew app:dependencies to find transitive mismatches.
• Exclusions can help, but only when you understand the dependency relationship.
• AndroidX migration is the durable fix for projects that are still maintained.