Kotlin "Unresolved reference" in CI

By Daniel Zoghalchali·Latchkey

The Kotlin compiler hit a name it cannot resolve. The class, function, or property you used is not on the compile classpath or is not imported.

What this error means

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

e: file:///src/main/kotlin/App.kt:5:8 Unresolved reference: gson
e: file:///src/main/kotlin/App.kt:12:14 Unresolved reference: toJson

Diagnose it: which runtime is on PATH?

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

Common causes

Dependency missing or wrong configuration

Using a library without adding it to implementation, or adding it only to testImplementation, leaves it off the main classpath.

Missing import

The symbol exists but the file does not import it, or the package was mistyped.

Generated code not built yet

References to kapt/ksp-generated or BuildConfig symbols fail if the generating task did not run before Kotlin compilation.

How to fix it

Add the dependency to the right configuration

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

Add the missing import

1. Confirm the fully qualified name of the symbol.
2. Add the matching import statement.
3. Re-sync Gradle so the IDE and CI agree on the classpath.

Ensure generators run before compile

Make the Kotlin compile task depend on the kapt/ksp/BuildConfig task so generated code exists first.

How to prevent it

• Keep dependency configurations correct.
• Run ./gradlew compileKotlin on a clean checkout.
• Verify generated sources are wired into the build.

Frequently asked questions

Related guides

References

• GitHub Actions documentation