この記事の要点

Java コンパイル時の 「package XXX does not exist / パッケージ XXX は存在しません」 エラー 主な原因: pom.xml / build.gradle に依存未追加 / classpath 不整合 / IDE のインデックスずれ / JDK バージョン違い 基本対処: ① mvn dependency:tree で確認 → ② mvn clean install → ③ IDE で Invalidate Caches → ④ JDK バージョン統一 ローカルにしか無い jar は mvn install:install-file で local repository に登録 IntelliJ / Eclipse のキャッシュ破損が原因のことも多い。ビルド成功するならまずキャッシュクリアを試す

このエラーの概要

Maven / Gradle / javac で Java をビルドしたとき、次のようなコンパイルエラーが出ます:

[ERROR] /src/main/java/com/example/UserService.java:[3,32]
        パッケージ org.springframework.stereotype は存在しません
[ERROR] /src/main/java/com/example/UserService.java:[5,2]
        シンボルを見つけられません
        シンボル: クラス Service

# 英語環境
[ERROR] package org.springframework.stereotype does not exist
[ERROR] cannot find symbol
        symbol:   class Service

Java のコンパイラ（javac）は import 行に書かれたクラスを classpath から探すのですが、見つからないとこのエラーが出ます。原因は単純な依存忘れから IDE 不整合まで多岐にわたります。

原因の切り分け

確認	方法	該当する場合の対処
pom.xml に依存があるか	mvn dependency:tree | grep spring	無ければ追加（対処1）
jar が local repo に落ちているか	ls ~/.m2/repository/org/springframework/...	無ければ mvn install（対処2）
javac の classpath	mvn -X compile | grep classpath	差異あれば clean（対処3）
IDE と Maven のずれ	コマンドラインで mvn compile が通るか	通れば IDE キャッシュ問題（対処4）
JDK バージョン	mvn -v / java -version	不一致なら統一（対処5）

対処1: 依存を pom.xml に追加

最も多い原因。import するクラスが含まれる jar (artifact) を pom.xml に書き忘れているだけです。

<!-- pom.xml -->
<dependencies>
    <!-- Spring Framework Core (org.springframework.stereotype.Service など) -->
    <dependency>
        <groupId>org.springframework</groupId>
        <artifactId>spring-context</artifactId>
        <version>6.1.5</version>
    </dependency>

    <!-- Spring Boot Starter (Spring Boot プロジェクトの場合) -->
    <dependency>
        <groupId>org.springframework.boot</groupId>
        <artifactId>spring-boot-starter</artifactId>
        <version>3.2.5</version>
    </dependency>

    <!-- Apache Commons Lang (org.apache.commons.lang3.*) -->
    <dependency>
        <groupId>org.apache.commons</groupId>
        <artifactId>commons-lang3</artifactId>
        <version>3.14.0</version>
    </dependency>
</dependencies>

追加したら必ず:

mvn clean install -DskipTests

# Gradle なら
gradle build --refresh-dependencies

対処2: jar がリポジトリに無い場合

Maven Central に無い、社内専用ライブラリの場合は ローカルリポジトリに手動で登録します:

# 単一 jar を local repo に登録
mvn install:install-file \
    -Dfile=./libs/internal-utils.jar \
    -DgroupId=com.example \
    -DartifactId=internal-utils \
    -Dversion=1.0.0 \
    -Dpackaging=jar

# pom.xml にも依存を書く
# <dependency>
#   <groupId>com.example</groupId>
#   <artifactId>internal-utils</artifactId>
#   <version>1.0.0</version>
# </dependency>

# Nexus / Artifactory に上げる場合
mvn deploy:deploy-file \
    -Dfile=internal-utils.jar \
    -DrepositoryId=nexus-internal \
    -Durl=https://nexus.example.com/repository/maven-releases/ \
    -DgroupId=com.example \
    -DartifactId=internal-utils \
    -Dversion=1.0.0 \
    -Dpackaging=jar

対処3: ローカルキャッシュ破損

ダウンロード途中で接続が切れると .lastUpdated ファイルが残り、それ以降そのアーティファクトは取れなくなります:

# 破損キャッシュを削除
find ~/.m2/repository -name "*.lastUpdated" -delete
find ~/.m2/repository -name "_remote.repositories" -delete

# あるいは特定アーティファクトだけ削除
rm -rf ~/.m2/repository/org/springframework/spring-context

# 強制再取得
mvn clean install -U   # -U = update snapshots & releases

# それでも直らないなら丸ごと削除（最終手段）
rm -rf ~/.m2/repository
mvn clean install

対処4: IDE のインデックス不整合（IntelliJ / Eclipse）

コマンドラインで mvn compile は通るのに IDE だけエラーを出すケースは IDE のキャッシュ問題です。

IntelliJ IDEA

1. File → Invalidate Caches… → Invalidate and Restart
2. 右側 Maven ペイン → Reimport All Maven Projects（リフレッシュアイコン）
3. File → Project Structure → Project SDK / Language level が pom.xml の <maven.compiler.source> と一致しているか確認

Eclipse

1. Project → Clean…
2. 右クリック → Maven → Update Project (Alt+F5) → Force Update of Snapshots/Releases にチェック
3. Window → Preferences → Java → Installed JREs で JDK パスを確認

対処5: JDK バージョン違い

例えば JDK 21 を要求するライブラリを JDK 11 でビルドすると、内部の API が無くて package not found 扱いになることがあります。

# 現在のバージョン
mvn -v
java -version
javac -version

# pom.xml で指定
# <properties>
#   <maven.compiler.source>17</maven.compiler.source>
#   <maven.compiler.target>17</maven.compiler.target>
# </properties>

# 切り替え (Linux) - update-alternatives
sudo update-alternatives --config java

# SDKMAN (推奨)
sdk install java 17.0.10-tem
sdk use java 17.0.10-tem

# Windows: 環境変数 JAVA_HOME と PATH の先頭を入れ替え

よくある具体例と必要な依存

エラーメッセージ	必要な依存
package javax.servlet does not exist	jakarta.servlet:jakarta.servlet-api (Jakarta EE 9+) または javax.servlet:javax.servlet-api
package org.junit.jupiter.api does not exist	org.junit.jupiter:junit-jupiter (scope=test)
package lombok does not exist	org.projectlombok:lombok + IDE で Lombok plugin 有効化
package com.fasterxml.jackson does not exist	com.fasterxml.jackson.core:jackson-databind
package org.slf4j does not exist	org.slf4j:slf4j-api + 実装 (logback-classic 等)

FAQ

Q: mvn dependency:tree には出るのに javac で見つからない
A: scope が test や provided になっている可能性。本番コードから使うなら compile（デフォルト）に変更してください。

Q: 急に出るようになった
A: pom.xml の自動編集で依存が消えたか、社内 Nexus がダウンしている可能性。mvn -X compile の冒頭でリポジトリ URL を確認してください。

Q: マルチモジュールで親プロジェクトを参照したい
A: 親で mvn install してローカル repo に入れるか、ルートから mvn -pl child-module -am compile で同時ビルドしてください。