Maven "Malformed \uxxxx encoding" エラーの解決方法

問題の概要

Maven の mvn install コマンドを実行中に java.lang.IllegalArgumentException: Malformed \uxxxx encoding エラーが発生することがあります。このエラーは、Maven の依存関係リゾルバーがプロパティファイルを読み込む際に、不正な Unicode エスケープシーケンス (\uxxxx) を検出した際に発生します。

エラーの特徴

• ローカル環境でのみ発生し、他のチームメンバーでは正常に動作する
• 以前は正常に動作していた環境で突然発生する
• JDK や Maven の再インストールでは解決しない場合がある

根本原因

このエラーの主な原因は、Maven のローカルリポジトリ内の resolver-status.properties ファイルが破損することです。これらのファイルには依存関係の解決状態が保存されていますが、以下の理由で破損することがあります：

1. マルチスレッドの問題: Maven の依存関係解決プロセスが複数のスレッドで同時に実行され、ファイルへの書き込み競合が発生する
2. Maven バージョンの不具合: 特定の Maven バージョンに存在するバグ（特に 3.8.1 以前）
3. Java バージョンの不一致: Maven が使用する Java バージョンと実際の環境の Java バージョンが異なる
4. 不正な文字の書き込み: プロパティファイルに NULL 文字 (\u0000) が誤って書き込まれる

解決方法

方法1: 破損したファイルの特定と削除（推奨）

最も安全で効果的な方法は、破損している特定のファイルのみを削除することです。

macOS/Linux の場合

# 破損ファイルの検索（NULL文字 \u0000 を含むファイルを検索）
grep -rnw ~/.m2 -e '\u0000'

# 破損ファイルを削除
grep -lrnw ~/.m2 -e '\u0000' | xargs rm

# または resolver-status.properties ファイルをすべて削除
find ~/.m2 -name "resolver-status.properties" -delete

Windows の場合

:: 破損ファイルの検索
FINDSTR /S /M "u0" resolver-status.properties

:: 検出されたファイルを手動で削除

カスタムリポジトリパスの場合

Maven のローカルリポジトリパスを変更している場合は、~/.m2/settings.xml の <localRepository> 設定を確認し、適切なパスを指定してください。

方法2: デバッグモードでの問題特定

どの依存関係が問題を引き起こしているか特定したい場合：

# 詳細エラー出力とデバッグ情報を有効化
mvn clean install -e -X

出力を確認し、エラーが発生する直前の依存関係解決の試行を特定します。

方法3: マルチスレッド問題の回避

Maven の依存関係解決をシングルスレッドで実行するように設定：

# Maven 実行時にスレッド数を1に制限
mvn clean install -Daether.metadataResolver.threads=1

IntelliJ IDEA を使用している場合は：

1. Settings → Build,Execution,Deployment → Maven → Runner を開く
2. VM Options フィールドに -Daether.metadataResolver.threads=1 を追加

方法4: Maven のアップグレード

Maven 3.8.1 以前を使用している場合、バージョンを 3.8.6 以上にアップグレードすることで問題が解決することがあります。

方法5: 完全なリポジトリの削除（最終手段）

上記の方法で解決しない場合、ローカルリポジトリ全体を削除します：

# ローカルリポジトリ全体を削除
rm -rf ~/.m2/repository

注意

この方法ではすべての依存関係が再ダウンロードされるため、時間がかかります。最初に他の方法を試すことを推奨します。

予防策

1. Maven バージョンの更新: 最新の安定版 Maven を使用する
2. 一貫した Java バージョンの使用:

   # JAVA_HOME の確認と設定
   echo $JAVA_HOME
   export JAVA_HOME=$(/usr/libexec/java_home)

3. ビルド環境のクリーン化: 定期的に resolver-status.properties ファイルを削除

   # 定期的なクリーンアップ用エイリアス（.bashrc や .zshrc に追加）
   alias mvn-cleanup="find ~/.m2 -name 'resolver-status.properties' -delete"

まとめ

Malformed \uxxxx encoding エラーは、Maven のローカルリポジトリ内のメタデータファイル破損が原因で発生します。ほとんどの場合、破損した resolver-status.properties ファイルを特定して削除することで解決できます。再発を防ぐためには、Maven の更新と適切な環境設定が重要です。

問題が解決しない場合は、デバッグ情報を有効にして正確な原因を特定し、必要に応じて Maven のスレッド数を制限することを検討してください。