Ktor + Koin 사용 시 NoClassDefFoundError 해결 기록

React + Ktor + Koin + Exposed 조합으로 커뮤니티 사이트를 개발하고 있었다.
의존성 주입은 Koin을 통해 관리하고, 라우팅은 기능별로 Route 모듈로 분리하고 있었다.

---

문제 상황

fun Route.userRoute() {
    val userService by inject<UserService>()

    route("/api/v1/user") {
        post {
            val request = call.receive<UserCreateRequest>()

            val result = userService.create(request)
        }
    }
}

이렇게 Route 내부에서 Koin의 inject()를 사용하려고 했는데, 다음과 같은 에러가 발생했다.

Exception in thread "main" java.lang.NoClassDefFoundError: io/ktor/server/routing/RoutingKt
	at org.koin.ktor.ext.RouteExtKt.getKoin(RouteExt.kt:74)
	at com.kcw.user.route.UserRouteKt.userRoute(UserRoute.kt:10)

• inject<UserService>() 호출 시 내부적으로 사용하는 getKoin()이 RoutingKt를 찾지 못해서 생기는 에러였다.
• Route 내부에서 의존성을 주입하려고 할 때 Koin의 Ktor 3 지원이 완전하지 않은 듯 보였다.

---

원인 분석

찾아보니 나만 겪는 문제는 아니었다.

https://github.com/InsertKoinIO/koin/issues/1716

해당 이슈에서는 ktor 3.x와 koin 3.x 조합에서 RouteExtKt.getKoin() 관련 오류가 종종 발생한다고 보고되고 있었다.
Ktor 3부터 내부 구조가 바뀌면서 기존 Koin Extension이 의존하는 클래스(RoutingKt)를 제대로 찾지 못하는 문제가 있는 듯하다.

---

해결 방법

Koin 공식 GitHub 이슈에서 다음과 같은 해결 방안을 발견했다:

// 기존 (문제 발생)
implementation("io.insert-koin:koin-ktor:3.x.x")

// 변경 (해결됨)
implementation("io.insert-koin:koin-ktor3:4.1.0-Beta7")

koin-ktor3는 Ktor 3.x에 맞춰 별도로 관리되는 Koin 확장 모듈이다.
아직 Beta이긴 하지만, 위 에러를 해결하기 위해선 이 버전을 사용하는 것이 현재로선 가장 확실한 해결책이었다.

---

적용 후 정상 동작

koin-ktor3 의존성으로 교체한 후 Route 내부에서 inject()를 정상적으로 사용할 수 있게 되었고, 서버도 에러 없이 실행되었다.

---

마무리

• Ktor 3.x와 Koin을 함께 사용할 때는 반드시 koin-ktor3 모듈을 사용하자.
• 아직 Beta 버전이지만, 기존 Ktor 확장 모듈과는 다른 방식으로 동작한다.
• 위와 같은 에러를 겪는다면 라이브러리 버전을 점검해보자.