Causes and Solutions for “Unresolved Reference” in Android Studio Kotlin

What Is “Unresolved Reference”?

Kotlin’s “Unresolved reference” is an error indicating that the compiler cannot resolve a name referenced in the code.

For example, suppose you have the following code.

val message = "Hello"
println(mesage)

The variable that is defined is message, but because it is written as mesage, Kotlin cannot find the corresponding variable.

In this case, “Unresolved reference” is displayed for mesage.

Cause 1: The Name or Spelling Is Incorrect

The first thing to check is whether there is a typing mistake in a class name, function name, variable name, or similar identifier.

Kotlin is also case-sensitive.

val userName = "Taro"

println(username)

In this example, userName and username are treated as different names.

The correct code is as follows.

val userName = "Taro"

println(userName)

If “Unresolved reference” is displayed, first check the spelling, uppercase and lowercase letters, and singular or plural forms in the relevant location.

Cause 2: An Import Statement Is Missing

If the class or function you are using exists in another package, “Unresolved reference” may occur if the required import statement has not been written.

In Android Studio, you may be able to place the cursor on the class name or other element showing the error and add the import through Quick Fix.

import android.widget.Toast

For example, when using Toast, the appropriate import is required.

If Android Studio displays suggestions, on a Mac you can generally check correction suggestions with Option + Enter.

Cause 3: The Variable or Function Is Outside Its Scope

In Kotlin, there is a defined range in which variables and functions can be used.

Referencing them from outside the scope in which they are defined causes “Unresolved reference”.

fun sample() {
    val text = "Hello"
}

fun test() {
    println(text)
}

In this example, text is a local variable defined inside sample().

Therefore, it cannot be referenced directly from test(), which is a different function.

If necessary, you need to define it as a class property or pass the value as a function argument.

Cause 4: Gradle Dependencies Are Missing

When using external libraries, AndroidX, or similar features, “Unresolved reference” may be displayed because the required library has not been added to Gradle.

For example, even if you use a class from a particular library in your code, Kotlin cannot reference that class if the dependency does not exist in the app’s build.gradle or build.gradle.kts.

dependencies {
    implementation("library dependency")
}

After adding a library, run Gradle Sync to apply it to the project.

Cause 5: Gradle Sync Has Not Completed Successfully

Even if the Gradle configuration itself is correct, Android Studio may not recognize dependencies correctly if Gradle Sync has not completed successfully.

In particular, if a large number of “Unresolved reference” errors appear immediately after adding a library or modifying Gradle-related files, check the status of Gradle Sync.

Run synchronization with the Gradle files from the Android Studio menu and check whether another error occurs during Sync.

If Gradle Sync itself is failing, you need to resolve the Gradle error before addressing “Unresolved reference”.

Cause 6: The Library or API Version Has Changed

When using old sample code, class names or function names may have been changed or removed in the library version you are currently using, resulting in “Unresolved reference”.

In this case, the error will not be resolved even if the spelling and import are correct.

Check the version of the library you are using and refer to the API or official documentation corresponding to that version.

Cause 7: The Package Name Is Incorrect

If you are referencing a class you created yourself from another file, also check the package name.

After moving files or changing the package structure, the package declaration or import statement may not have been updated correctly.

package com.example.sample

Check which package the class you want to reference belongs to and confirm that it matches the import destination.

Cause 8: Java and Kotlin Code Are Mixed

In Android projects, Java and Kotlin can also be used within the same project.

However, depending on how methods and fields are defined on the Java side, they may not be referenceable from Kotlin using the expected names.

If you are using a class created in Java from Kotlin, check whether the class and methods are properly exposed on the Java side and whether the package and import are correct.

Cause 9: There Is a Problem with the View Binding or Data Binding Configuration

When using View Binding or Data Binding, “Unresolved reference” may be displayed for a Binding class.

For View Binding, check whether View Binding is enabled in the module configuration.

android {
    buildFeatures {
        viewBinding = true
    }
}

After changing the configuration, run Gradle Sync.

The generated Binding class name is also determined based on the XML layout file name.

activity_main.xml
↓
ActivityMainBinding

If you have changed the XML file name, also check the Binding class name used in the code.

Cause 10: There Is a Problem with Jetpack Compose Imports or Dependencies

Even in projects using Jetpack Compose, “Unresolved reference” may be displayed for Compose-related functions.

For example, if Text, Column, or Modifier cannot be resolved, check the corresponding imports and Compose-related dependencies.

Compose sample code may contain APIs with the same or similar names across multiple libraries, so it is also important to check whether the import automatically added by Android Studio is correct.

When the Code Is Highlighted in Red in Android Studio but Still Builds

In rare cases, there may be no problem with the code itself, but red error indicators such as “Unresolved reference” may remain only in the Android Studio editor.

In this case, actually build the project and check whether a compilation error occurs.

If the project builds successfully but only the editor display is incorrect, Android Studio’s index or cache may not have been updated properly.

Restarting Android Studio or running Gradle Sync again may resolve the issue.

Try Clean Project or Rebuild Project

If you cannot find an obvious problem with the code or Gradle configuration, rebuilding the project is another method you can try.

Although the menu structure differs depending on the Android Studio version, performing an operation equivalent to Clean or Rebuild may remove the effects of previously generated build results.

However, if the cause of “Unresolved reference” is a spelling mistake or a missing dependency, Clean or Rebuild alone will not resolve the issue.

Check for Cache Problems

If there is a problem with Android Studio’s internal state or index, it may appear unable to resolve references even when the code is correct.

If Gradle Sync and restarting Android Studio do not resolve the issue, and no problem can be found in the code or dependencies, suspect an issue with the IDE cache or index.

When a Large Number of “Unresolved Reference” Errors Appear

If a large number of “Unresolved reference” errors suddenly appear throughout the project rather than in only one location, it may be better to suspect the project configuration rather than individual spelling mistakes.

In particular, check for Gradle Sync failures, errors in build.gradle or build.gradle.kts, plugin problems, and failures when retrieving libraries.

If there is a Gradle error, dependencies may not be loaded correctly, causing many classes that should normally be available to appear as “Unresolved reference” at the same time.

Order of Checks When “Unresolved Reference” Appears

If you do not know the cause, checking the following items in order can make it easier to isolate the problem.

Check What the Error Message Refers To

When resolving “Unresolved reference”, it is important to check not only the error name, but also what is being shown as an unresolved reference.

For example, if the target is a variable you created yourself, check its spelling and scope; if it is an Android class, check the import; if it is a class from an external library, check the Gradle dependencies; and if it is a Binding class, check the View Binding configuration. The location you need to check differs depending on the target.

Unresolved reference: Toast
→ Check the import

Unresolved reference: ActivityMainBinding
→ Check View Binding and the layout file name

Unresolved reference: userName
→ Check the variable name and scope

An external library class is shown as Unresolved reference
→ Check Gradle dependencies and Sync

Summary

“Unresolved reference” in Kotlin in Android Studio is an error that occurs when Kotlin cannot find a class, function, variable, or other element that the code is trying to reference.

Particularly common causes include spelling mistakes, missing imports, scope issues, missing Gradle dependencies, and Gradle Sync failures.

If the error occurs in only one location, first check the name, import, and scope. On the other hand, if a large number of errors appear throughout the project, checking for problems with Gradle or the project configuration can make it easier to narrow down the cause.

Also, if you are using old sample code, it is important to check whether the same API is available in the version of the library you are currently using.