Android Studio: Causes of “Unresolved reference” and How to Fix It

What Is Unresolved reference?

Unresolved reference
is an error displayed when the Kotlin compiler cannot resolve a name written in the code.

For example,
even if you use a class called
SampleClass
in your code,
this error may occur if the class does not exist in the project,
has not been imported,
or the required library has not been added.

val sample = SampleClass()

If Android Studio or the Kotlin compiler cannot find
SampleClass,
an error such as the following is displayed.

Unresolved reference: SampleClass

Typical Error Messages

Unresolved reference: SampleClass

For a function,
it may be displayed as follows.

Unresolved reference: sampleFunction

In Android apps,
errors may also occur for names such as the following.

Unresolved reference: R
Unresolved reference: BuildConfig
Unresolved reference: lifecycleScope
Unresolved reference: viewModels

The cause you should check differs depending on which name is causing the
Unresolved reference
error.

First, Check the Name Causing the Error

When
Unresolved reference
occurs,
first check the name displayed after the error.

Unresolved reference: SampleClass

In this case,
check what
SampleClass
refers to.

The way you investigate the cause differs depending on whether it is
a class you created yourself,
a class from the Android SDK,
or a class from an external library.

Cause 1: The Name Is Misspelled

The simplest cause is a spelling mistake in a class name,
variable name,
function name,
or similar identifier.

For example,
if the actual function name is
showMessage
but it is written as follows.

showMesage()

Correct it to the proper name.

showMessage()

Kotlin is also case-sensitive,
so be careful about differences such as the following.

SampleClass
sampleClass

Cause 2: An import Statement Is Missing

If the class or function you want to use exists in another package,
Unresolved reference
may occur because the required import statement has not been added.

For example,
when using
Intent,
an import such as the following may be required.

import android.content.Intent

In Android Studio,
import candidates may be displayed
by placing the cursor on the class name causing the error
or by using a quick fix.

Check Whether You Imported the Wrong Class with the Same Name

Even if an import statement exists,
you may have imported a different class with the same name from the one you intended to use.

Especially when multiple libraries contain classes with the same name,
check the package name in the import statement as well.

import com.example.library.SampleClass

If the class you want to use is in another package,
change the import to the correct one.

Cause 3: A Required Gradle Dependency Has Not Been Added

If you are using a class or function from an external library,
Unresolved reference
occurs if the required library has not been added to Gradle.

For example,
to use a class from a certain library,
you need to add the dependency to the module’s
build.gradle
or
build.gradle.kts.

dependencies {
    implementation("com.example:sample-library:VERSION")
}

Specify the version of the library you want to use in
VERSION.

Check which library contains the API you are using
and whether the required dependency has been added.

Run Gradle Sync After Adding Dependencies

If you change
build.gradle
or
build.gradle.kts,
run Gradle Sync.

If Gradle synchronization has not been completed,
Android Studio may not recognize the class
even if the library has been added.

After running Gradle Sync,
check the code again.

Cause 4: The API Was Removed After a Library Version Change

If
Unresolved reference
occurs after updating a library,
the class,
function,
property,
or other API you were using
may have been changed or removed in the new version.

For example,
an API that existed in an older version
may have been renamed or moved to another class in a newer version.

Check the library’s official documentation or change history
and modify the code to use an API available in the version you are currently using.

Cause 5: A Variable or Function Is Out of Scope

Even if a variable or function is defined,
Unresolved reference
occurs if it is in a location that cannot be referenced from the current code.

For example,
this occurs when you try to use a variable defined inside a function
from outside that function.

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

fun anotherSample() {
    println(message)
}

In this example,
message
is a local variable defined inside
sample(),
so it cannot be referenced from
anotherSample().

If necessary,
move the variable or function to a location where it can be referenced.

Cause 6: A Class or Function Was Deleted or Moved

Unresolved reference
may also occur if a class or function has been deleted during refactoring
or moved to another package.

Check whether an import that refers to the old package name remains.

import com.example.old.SampleClass

If the class was moved to another package,
modify the import to match the new package.

Cause 7: A Class in Another Module Cannot Be Referenced

In an Android project made up of multiple modules,
a dependency between modules may be required
to use a class that exists in another module.

For example,
if you want to use the
samplelibrary
module from the
app
module,
add a dependency such as the following.

dependencies {
    implementation(project(":samplelibrary"))
}

Even if the module itself exists in the project,
classes in that module cannot be referenced
if the required dependency has not been configured.

Cause 8: R Becomes an Unresolved reference

In Android apps,
an error such as the following may occur.

Unresolved reference: R

R
is a class generated for referencing Android resources.

If
R
cannot be referenced,
the cause may be an error in an XML resource or another resource
rather than the Kotlin code itself.

Check whether there are errors in XML files inside the
res
folder,
whether resource names are correct,
and whether another error occurred earlier during the build.

Check Whether the Wrong R Has Been Imported

For errors related to
R,
also check whether an unintended
R
class has been imported.

For example,
check the import section of the code
and make sure that an
R
class unrelated to the app’s resources has not been added.

If there is an unnecessary import,
remove it
and make sure the project refers to the correct resources.

Cause 9: The Resource Name Does Not Exist

Even if
R
itself is recognized,
only a specified resource name may become an
Unresolved reference.

R.id.sampleButton

In this case,
check whether an ID called
sampleButton
is actually defined in the XML.

android:id="@+id/sampleButton"

Also check the spelling and capitalization of the resource name
and the layout file being used.

Cause 10: BuildConfig Becomes an Unresolved reference

In Android projects,
an error such as the following may occur.

Unresolved reference: BuildConfig

BuildConfig
is a class generated during the build.

Depending on the module you are using
and the Android Gradle Plugin settings,
you may need to check the
BuildConfig
generation settings.

If necessary,
check whether
buildConfig
is enabled in the Android module settings.

android {
    buildFeatures {
        buildConfig = true
    }
}

Also check whether you are accidentally referring to
BuildConfig
from another module.

Cause 11: A Dependency or import for an Extension Function Is Missing

In Kotlin,
you may use APIs provided as extension functions.

For example,
features provided by AndroidX KTX libraries
become
Unresolved reference
if the required dependency or import is missing.

If the class itself is recognized
but only a specific function or property is not,
check which library provides that API.

When lifecycleScope Becomes an Unresolved reference

In Android development,
an error such as the following may occur.

Unresolved reference: lifecycleScope

In this case,
check whether the required Lifecycle-related KTX dependency and import are configured.

Also check whether the class in which
lifecycleScope
is being used
has the corresponding Lifecycle.

When viewModels Becomes an Unresolved reference

In code such as the following,
viewModels
may not be recognized.

private val viewModel: SampleViewModel by viewModels()

In this case,
check the KTX library corresponding to the Activity or Fragment you are using,
the required imports,
dependencies,
and other settings.

Even APIs with the same name
may have different usage requirements depending on the class or library being used.

Cause 12: Kotlin or Library Versions Are Not Compatible

If the versions of Kotlin,
the Android Gradle Plugin,
or the libraries you are using are incompatible,
APIs that should normally be available may not be recognized correctly.

If the error occurs immediately after updating a library,
Kotlin,
Gradle,
the Android Gradle Plugin,
or similar components,
check the combination of versions.

Check the official documentation for the library you are using
and use a supported combination of versions.

Cause 13: Source Sets Such as debug and release Are Different

In Android projects,
source sets such as
debug,
release,
and Product Flavors can be used in addition to
main.

src/main/
src/debug/
src/release/

If a class exists only in
debug,
that class cannot be referenced from a
release
build.

If
Unresolved reference
occurs only in a specific build variant,
check the source set in which the class is located.

Cause 14: Generated Code Has Not Been Created

If you are using classes generated by a library or build tool,
Unresolved reference
may occur because the code generation process did not complete successfully.

In this case,
check Build Output
and see whether another error related to code generation or a Gradle task
occurred before
Unresolved reference.

Cause 15: There Is a Problem with References Between Java and Kotlin

In projects that mix Java and Kotlin,
problems with names or access scope may occur
when referencing Java classes or methods from Kotlin.

Check whether the target class or method is
private,
whether it exists in the correct package,
and whether it is in a state that can be referenced from Kotlin.

Check Whether Gradle Sync Resolves the Problem

If
Unresolved reference
is displayed after adding or changing a library,
first run Gradle Sync.

If Gradle synchronization fails,
fix the error displayed during Sync first.

After Sync completes successfully,
check the relevant code again.

Run Clean or Rebuild

If the error remains even after modifying the code or dependencies,
old build results or intermediate files may be affecting the project.

From the
Build
menu in Android Studio,
perform the equivalent of Clean or Rebuild
available in the version of Android Studio you are using.

After that,
build again and check whether the error has been resolved.

When Only Android Studio Shows Red Error Text

Even when the actual Gradle build succeeds,
red error highlighting such as
Unresolved reference
may remain only in the Android Studio editor.

In this case,
the project information on the IDE side
and the Gradle state may not match.

First run Gradle Sync,
reload the project,
and check whether the state is updated.

If the build itself is also failing,
do not treat it as only an IDE display problem;
check the compilation errors displayed in Build Output.

If Unresolved reference Still Cannot Be Resolved

If you do not know the cause,
check each item in order based on the name causing the error.

When Many Unresolved reference Errors Are Displayed

Many
Unresolved reference
errors may be displayed at the same time
in a single file or throughout the project.

In this case,
it does not necessarily mean that every error needs to be fixed individually.

For example,
if one library is not being loaded,
many classes and functions contained in that library
may all become
Unresolved reference
at once.

Also,
if generation of
R
fails,
many resource references may become errors at the same time.

Summary

Android Studio’s
Unresolved reference
is an error that occurs when the Kotlin compiler cannot find
a class,
variable,
function,
property,
or other name specified in the code.

Main causes include spelling mistakes,
missing imports,
missing Gradle dependencies,
library API changes,
scope problems,
dependencies between modules,
and differences in source sets.

If classes generated during the Android build,
such as
R
or
BuildConfig,
are not recognized,
also check whether another error has occurred
in the settings or resources from which they are generated.

If many
Unresolved reference
errors occur at the same time,
do not fix each one individually;
first check for a common cause related to Gradle Sync,
libraries,
resources,
or code generation.