Maven依存関係バージョン衝突の原因と解決策

概要

Mavenの依存関係バージョン衝突は、複数のライブラリが同じアーティファクトの異なるバージョンを要求する場合に発生します。ビルド時にはエラーにならず、実行時に NoSuchMethodError や ClassNotFoundException として現れることが多いです。

エラーメッセージ

java.lang.NoSuchMethodError: com.google.common.collect.ImmutableMap.toImmutableMap()

java.lang.ClassNotFoundException: org.apache.commons.lang3.StringUtils

[WARNING] Omitted dependency: com.google.guava:guava:jar:30.0-jre
  managed from 31.1-jre

1
2
3
4
5
# dependency:tree -Dverbose で確認できる衝突
[INFO] +- com.example:lib-a:jar:1.0:compile
[INFO] |  \- com.google.guava:guava:jar:28.0-jre:compile (version managed from 30.0-jre)
[INFO] +- com.example:lib-b:jar:2.0:compile
[INFO] |  \- (com.google.guava:guava:jar:31.1-jre:compile - omitted for conflict with 28.0-jre)

原因

1. 推移的依存関係のバージョン不一致

ライブラリAがGuava 28を、ライブラリBがGuava 31を要求し、Mavenが古いバージョンを選択する場合があります。

2. dependencyManagementによるバージョン固定

親POMやdependencyManagementで古いバージョンに固定されている場合があります。

3. Mavenの最近勝ち（nearest wins）戦略

Mavenは依存関係ツリーで「最も近い」バージョンを選択します。これが意図しない古いバージョンになる場合があります。

解決策

1. 依存関係ツリーで衝突を確認

1
2
3
4
5
# 衝突を含む詳細な依存関係ツリー
mvn dependency:tree -Dverbose

# 特定のアーティファクトをフィルタ
mvn dependency:tree -Dincludes=com.google.guava

2. dependencyManagementでバージョンを統一

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<!-- pom.xml -->
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
            <version>33.0.0-jre</version> <!-- 最新の互換バージョンに統一 -->
        </dependency>
    </dependencies>
</dependencyManagement>

3. exclusionsで競合する依存関係を除外

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<dependency>
    <groupId>com.example</groupId>
    <artifactId>lib-a</artifactId>
    <version>1.0</version>
    <exclusions>
        <exclusion>
            <groupId>com.google.guava</groupId>
            <artifactId>guava</artifactId>
        </exclusion>
    </exclusions>
</dependency>

4. maven-enforcer-pluginでバージョン衝突を検出

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
<build>
    <plugins>
        <plugin>
            <groupId>org.apache.maven.plugins</groupId>
            <artifactId>maven-enforcer-plugin</artifactId>
            <version>3.4.1</version>
            <executions>
                <execution>
                    <id>enforce-dependency-convergence</id>
                    <goals>
                        <goal>enforce</goal>
                    </goals>
                    <configuration>
                        <rules>
                            <dependencyConvergence/>
                        </rules>
                    </configuration>
                </execution>
            </executions>
        </plugin>
    </plugins>
</build>

5. BOM（Bill of Materials）を使用

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
<dependencyManagement>
    <dependencies>
        <dependency>
            <groupId>org.springframework.boot</groupId>
            <artifactId>spring-boot-dependencies</artifactId>
            <version>3.2.4</version>
            <type>pom</type>
            <scope>import</scope>
        </dependency>
    </dependencies>
</dependencyManagement>

デバッグ方法

1
2
3
4
5
6
7
8
# 依存関係の衝突を一覧表示
mvn dependency:tree -Dverbose | grep "omitted for conflict"

# 依存関係の分析
mvn dependency:analyze

# 重複する依存関係を表示
mvn dependency:analyze-duplicate

Maven依存関係バージョン衝突

概要