Mavenのビルドが突然失敗する理由あるある - Web開発における知見共有系ページ

Mavenのビルドが「昨日まで動いていたのに、今日突然失敗する」という現象は、珍しい話ではありません。多くの場合、pom.xmlを書き換えた覚えがなくても、外部要因や環境差分が積み重なって表面化しています。つまり、ビルド失敗は偶然ではなく、よくあるパターンのどれかに当てはまることがほとんどです。

この記事では、Mavenのビルドが突然失敗する理由を「現場で本当によく見るあるある」に絞って整理します。単なる原因列挙ではなく、「実際にどう壊れるか」「なぜ気づきにくいか」「どう防ぐか」まで踏み込んで解説します。

多くのケースで共通しているのは、「自分が直接触っていない場所が変わっている」という点です。Mavenはローカル環境、ネットワーク、リポジトリ、プラグインなど、多数の外部要素に依存しています。そのため、プロジェクト自体が変わっていなくても、結果が変わる余地が常にあります。

最初に疑うべき定番ポイントが、ローカルの.m2リポジトリです。ビルド途中で通信が切れたり、強制終了したりすると、jarやpomが中途半端な状態で保存されることがあります。

この状態になると、次のようなエラーが出がちです。

> Could not resolve dependencies for project
> Failed to read artifact descriptor

一見すると依存関係の定義ミスに見えますが、実際にはローカルキャッシュが壊れているだけ、ということが少なくありません。

対処としては、問題のありそうなライブラリを個別に削除するか、最悪の場合は.m2を丸ごと削除して再取得します。

rm -rf ~/.m2/repository/対象のグループID

ただし、.m2を全削除すると再ダウンロードに時間がかかる点には注意が必要です。CI環境と挙動を揃えたい場合にも、ローカル削除は有効ですが、通信環境が不安定な場所では逆効果になることもあります。

「何もしていないのに落ちた」というケースで意外と多いのが、リモートリポジトリ側の問題です。Maven Centralや社内Nexus、Artifactoryが一時的に不調になると、依存関係の解決に失敗します。

特に、以下のような条件が重なると再現しやすくなります。

この場合、同じコマンドを時間を置いて再実行すると、あっさり通ることもあります。原因がコード側にないため、ログだけ見て深追いしすぎると時間を無駄にしがちです。

snapshotは便利ですが、突然ビルドが壊れる原因の代表格でもあります。昨日取得したsnapshotと、今日取得したsnapshotは「同じバージョン名でも中身が違う」可能性があります。

例えば、内部ライブラリのsnapshotに破壊的変更が入った場合、依存している全プロジェクトが連鎖的に失敗します。

この問題は、「snapshotを使っている限り起こり得る」という前提を理解していないと、非常にハマりやすいです。安定性を重視するフェーズでは、release版への切り替えを検討した方が無難です。

依存ライブラリだけでなく、Mavenプラグインもビルド失敗の原因になります。

pluginManagementでバージョンを固定していない場合、Mavenが暗黙的に新しいプラグインを取得することがあります。その結果、今まで通っていたビルドが突然通らなくなります。

特に影響が出やすいのは以下のプラグインです。

Javaのバージョンアップと絡むと、source/targetの扱いが変わり、警告では済まずエラーになることもあります。プラグインのバージョンは、可能な限り明示的に固定しておくのが安全です。

ローカルのJavaがいつの間にか切り替わっているケースもあります。SDKMANやjenvを使っていると、別プロジェクトの影響でJavaのバージョンが変わることがあります。

その結果、

といったエラーが突然出ます。pom.xml側でmaven-compiler-pluginを設定していても、実行JDK自体がズレていると防げません。

CIでは通るのにローカルで落ちる場合、この差分を疑う価値は高いです。

ここまでの内容は、特定の人だけが遭遇する話ではありません。ただし、次のような状況では遭遇頻度が上がりやすいです。

逆に、依存関係とプラグインを厳密に固定し、CIを基準に運用しているプロジェクトでは、突然の失敗は起きにくくなります。

Mavenのビルド失敗対応で注意したいのは、「とりあえずキャッシュ削除」で思考停止しないことです。確かに直ることは多いですが、根本原因を理解しないままだと再発します。

また、以下の点もリスクとして意識しておく必要があります。

ビルドが突然失敗したときほど、落ち着いて「どこが変わった可能性があるか」を切り分ける姿勢が重要です。

Mavenのビルドが突然失敗する問題は、完全にゼロにはできません。ただし、頻度と影響は確実に下げられます。

これらを意識するだけで、「原因不明で詰む」時間は大きく減ります。Mavenは癖のあるツールですが、仕組みを理解すると、失敗のパターンも見えてきます。突然のビルド失敗に振り回されないためにも、あるあるを知っておくこと自体が最大の対策と言えるでしょう。