はじめに

この記事は「Spring Boot 3系＋Kotlin」で新規プロジェクトを立ち上げたものの、ビルドで躓いてしまった開発者さん向けです。
特に「Gradleタスクが失敗する」「Kaptが原因でコンパイルエラー」「JDKバージョンが合わない」という3つのエラーに集中して解説します。
記事を読み終えると、ビルドログを素早く読み分け、該当箇所を修正して正常にbootRunまで到達できるようになります。
私自身、Spring Boot 2→3へマイグレーションした際に1日溶かしてしまったため、同じ轍は避けてほしいという思いでまとめました。

前提知識

  • Kotlinの基礎文法（関数・クラス定義レベル）
  • Gradle Kotlin DSLの記述がどこにあるか把握していること
  • ターミナルで./gradlew buildが実行できる環境
  • Java 17以降がインストール済みであること

Spring Boot 3系でなぜビルドが壊れやすいのか

Spring Boot 3系では、Spring Framework 6ベースへと移行され、以下の大きな変更点がビルド失敗の引き金になります。

  1. Java 17必須
    これまでのJava 8や11では起動すらしません。GradleのtoolchainやsourceCompatibilityを見直す必要があります。

  2. Gradle 7.5+推奨
    古いWrapperを使ったままだと、プラグイン解決時にCould not resolve系エラーが出ます。

  3. Kaptの後継KSPへの移行期
    Kotlin 1.9+ではKaptがメンテナンスモードに入り、公式はKSP（Kotlin Symbol Processing）を推奨。
    しかし、Springのメタプロセッサは未だKapt依存のため、両方を混在させるとビルドが複雑になります。

これらが交差するため、「動かない→検索しても古い情報ばかり→さらに動かない」という負の連鎖が生まれます。

ビルドエラーの3大パターンと実践的な直し方

パターン1: 「Unsupported class file major version」エラー

症状

Execution failed for task ':compileKotlin'.
> Unsupported class file major version 61

原因

GradleがJDK 17で動いていない（=JDK 11以下でビルドしている）

修正手順

  1. IDEのGradle JVMを確認
    IntelliJ → Preferences → Build Tools → Gradle → Gradle JVMを17に設定
  2. gradle.propertiesに以下を追加 properties org.gradle.java.home=/usr/lib/jvm/java-17-openjdk-amd64
  3. build.gradle.ktsでtoolchainを明示 kotlin java { toolchain { languageVersion.set(JavaLanguageVersion.of(17)) } }
  4. ./gradlew clean buildを再実行

パターン2: Kaptが原因で「Cannot find annotation processor」

症状

Execution failed for task ':kaptKotlin'.
> Cannot find annotation processor class 'org.springframework.boot.configurationprocessor.ConfigurationMetadataAnnotationProcessor'

原因

Kaptの設定が足りないか、依存が古い。

修正手順

  1. pluginsブロックに追加 kotlin plugins { id("org.springframework.boot") version "3.2.5" id("io.spring.dependency-management") version "1.1.4" kotlin("jvm") version "1.9.23" kotlin("plugin.spring") version "1.9.23" kotlin("kapt") version "1.9.23" }
  2. dependenciesで明示 kotlin dependencies { kapt("org.springframework.boot:spring-boot-configuration-processor") }
  3. Gradleキャッシュをクリア bash ./gradlew clean rm -rf .gradle build ./gradlew build --no-daemon

パターン3: Gradleメタデータ解決失敗「Could not resolve…」

症状

Could not resolve: org.springframework.boot:spring-boot-gradle-plugin:3.2.5

原因

リポジトリ設定が古いか、プロキシ/ファイアウォールでMaven Centralに到達していない。

修正手順

  1. settings.gradle.ktsでリポジトリを追加 kotlin pluginManagement { repositories { gradlePluginPortal() mavenCentral() maven { url = uri("https://repo.spring.io/milestone") } } }
  2. build.gradle.ktsでも重複定義 kotlin repositories { mavenCentral() maven { url = uri("https://repo.spring.io/milestone") } }
  3. プロキシ環境下ならgradle.propertiesに properties systemProp.http.proxyHost=proxy.example.com systemProp.http.proxyPort=8080 systemProp.https.proxyHost=proxy.example.com systemProp.https.proxyPort=8080

ハマりどころ：KaptとKSPの混在

Spring Boot公式がKSP対応を急ピッチで進めているとはいえ、spring-boot-configuration-processorはまだKapt依存です。
そのため、KSPを有効にしてしまうと

kapt.kotlin.options: Kapt has already been configured

というエラーに遭遇します。
結論として、Spring Boot 3系では当面Kaptを使い、KSPは使わない方が無難です。

解決策：Kaptオンリー構成の最小プロジェクト

以下はエラーが出にくい最小テンプレートです。
build.gradle.kts

Kotlin

plugins {
    id("org.springframework.boot") version "3.2.5"
    id("io.spring.dependency-management") version "1.1.4"
    kotlin("jvm") version "1.9.23"
    kotlin("plugin.spring") version "1.9.23"
    kotlin("kapt") version "1.9.23"
}

group = "com.example"
version = "0.0.1-SNAPSHOT"
java.sourceCompatibility = JavaVersion.VERSION_17

repositories {
    mavenCentral()
}

dependencies {
    implementation("org.springframework.boot:spring-boot-starter-web")
    implementation("com.fasterxml.jackson.module:jackson-module-kotlin")
    implementation("org.jetbrains.kotlin:kotlin-reflect")
    kapt("org.springframework.boot:spring-boot-configuration-processor")
    testImplementation("org.springframework.boot:spring-boot-starter-test")
}

tasks.withType<Test> {
    useJUnitPlatform()
}

この状態で./gradlew bootRunすれば、90%の確率で成功します。

まとめ

本記事では、Spring Boot 3系＋Kotlinでビルドがコケる3大パターン（JDKバージョン、Kapt設定、Gradle解決失敗）を取り上げ、それぞれの原因と実践的な修正手順を解説しました。

  • Java 17必須をGradleレベルで明示する
  • Kaptは残しつつ、KSPと混在させない
  • リポジトリ設定を二箇所（pluginManagementとdependencies）で揃える

これらを意識することで、ビルドエラーの手間を大幅に削減できます。
次回は「KSP完全移行時のメタデータ自動生成」と「Gradle Version Catalogsでマルチモジュールを保守する方法」を掘り下げる予定です。

参考資料