Kotlin "Unresolved reference" variant in CI

By Kaveh Alemi·Latchkey

The Kotlin compiler hit a name it cannot resolve - a property, function, or extension that is not imported or not on the compile classpath.

What this error means

The build fails with Unresolved reference: foo, pointing at the symbol. It is deterministic; the name is simply not visible.

gradle

e: file:///src/main/kotlin/App.kt:9:16 Unresolved reference: firstOrNull
e: file:///src/main/kotlin/App.kt:11:8 Unresolved reference: gson

Diagnose it: which runtime is on PATH?

Terminal

which -a <runtime>
<runtime> --version
cat .tool-versions .nvmrc .ruby-version .python-version 2>/dev/null

Common causes

Extension import missing

Extension functions must be imported by their declaration package; without the import the receiver appears to lack the member.

Dependency in the wrong configuration

A library is used in main code but declared only under testImplementation, so it is off the main classpath.

Generated symbol not built yet

References to ksp/kapt-generated or BuildConfig symbols fail when the generating task has not run.

How to fix it

Import the extension or symbol

Add the import for the extension declaration package.

App.kt

import kotlin.collections.firstOrNull
import com.google.gson.Gson

Move the dependency to the right configuration

build.gradle.kts

dependencies {
  implementation("com.google.code.gson:gson:2.11.0")
}

Ensure generators run before compile

Wire the ksp/kapt/BuildConfig task ahead of compileKotlin so generated symbols exist.

How to prevent it

Keep dependency configurations correct.
Import extensions explicitly.
Run ./gradlew compileKotlin on a clean checkout.

Frequently asked questions

What causes Kotlin "Unresolved reference" variant in CI?

There are 3 common causes: extension import missing, dependency in the wrong configuration, and generated symbol not built yet. Extension functions must be imported by their declaration package; without the import the receiver appears to lack the member.

How do I fix Kotlin "Unresolved reference" variant in CI?

There are 3 fixes depending on which cause you have: import the extension or symbol, move the dependency to the right configuration, and ensure generators run before compile. Work through them in order, since the first is the most common.

What does Kotlin "Unresolved reference" variant in CI actually mean?

The build fails with Unresolved reference: foo, pointing at the symbol.

How do I stop Kotlin "Unresolved reference" variant in CI happening again?

Keep dependency configurations correct. The prevention section lists 3 changes that keep it from recurring.

References

GitHub Actions documentation