Android Studio「Unresolved reference」の原因と解決方法

Unresolved referenceとは

Unresolved referenceは、
Kotlinコンパイラがコード内に書かれている名前を解決できない場合に表示されるエラーです。

たとえば、
コード内で
SampleClass
というクラスを使用しているにもかかわらず、
そのクラスがプロジェクト内に存在しない、
importされていない、
または必要なライブラリが追加されていない場合などに発生します。

val sample = SampleClass()

Android StudioやKotlinコンパイラが
SampleClass
を見つけられない場合、
次のようなエラーが表示されます。

Unresolved reference: SampleClass

代表的なエラー表示

Unresolved reference: SampleClass

関数の場合は、
次のように表示されることがあります。

Unresolved reference: sampleFunction

Androidアプリでは、
次のような名前についてエラーが発生することもあります。

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

どの名前が
Unresolved reference
になっているかによって、
確認すべき原因が異なります。

まずエラーになっている名前を確認する

Unresolved referenceが発生した場合は、
最初にエラーの後に表示されている名前を確認します。

Unresolved reference: SampleClass

この場合は、
SampleClass
が何を指しているのか確認します。

自分で作成したクラスなのか、
Android SDKのクラスなのか、
外部ライブラリのクラスなのかによって、
原因の調べ方が変わります。

原因1：名前のスペルが間違っている

最も単純な原因は、
クラス名、変数名、関数名などのスペルミスです。

たとえば、
実際の関数名が
showMessage
であるにもかかわらず、
次のように記述している場合です。

showMesage()

正しい名前へ修正します。

showMessage()

Kotlinでは大文字と小文字も区別されるため、
次のような違いにも注意します。

SampleClass
sampleClass

原因2：import文が不足している

使用するクラスや関数が別のパッケージに存在している場合は、
必要なimport文が追加されていないことで
Unresolved reference
になることがあります。

たとえば、
Intentを使用する場合は、
必要に応じて次のようなimportが必要です。

import android.content.Intent

Android Studioでは、
エラーになっているクラス名へカーソルを合わせたり、
クイックフィックスを利用したりすることで、
import候補が表示される場合があります。

同名クラスを間違ってimportしていないか確認する

import文が存在していても、
意図したものとは別の同名クラスをimportしている場合があります。

特に複数のライブラリに同じ名前のクラスが存在する場合は、
import文のパッケージ名まで確認します。

import com.example.library.SampleClass

使用したいクラスが別のパッケージにある場合は、
正しいimportへ変更します。

原因3：必要なGradle依存関係が追加されていない

外部ライブラリのクラスや関数を使用している場合、
必要なライブラリがGradleへ追加されていないと
Unresolved reference
が発生します。

たとえば、
あるライブラリのクラスを使用するには、
モジュールの
build.gradle
または
build.gradle.kts
に依存関係を追加する必要があります。

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

VERSIONには、
使用するライブラリのバージョンを指定します。

使用しているAPIがどのライブラリに含まれているのか確認し、
必要な依存関係が追加されているか確認します。

依存関係を追加したらGradle Syncを実行する

build.gradleや
build.gradle.kts
を変更した場合は、
Gradle Syncを実行します。

Gradleの同期が完了していないと、
ライブラリを追加していてもAndroid Studio側でクラスを認識できないことがあります。

Gradle Syncを実行したあと、
再度コードを確認します。

原因4：ライブラリのバージョン変更でAPIがなくなった

ライブラリを更新したあとに
Unresolved reference
が発生した場合は、
使用していたクラス、関数、プロパティなどが
新しいバージョンで変更または削除されている可能性があります。

たとえば、
古いバージョンでは存在したAPIが、
新しいバージョンでは別の名前や別のクラスへ変更されていることがあります。

ライブラリの公式ドキュメントや変更履歴を確認し、
現在使用しているバージョンで利用できるAPIへ修正します。

原因5：変数や関数がスコープ外にある

変数や関数が定義されていても、
現在のコードから参照できない場所にある場合は
Unresolved reference
が発生します。

たとえば、
関数の中で定義した変数を、
その関数の外側から使用しようとした場合です。

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

fun anotherSample() {
    println(message)
}

この例では、
message
は
sample()
の内部で定義されたローカル変数であるため、
anotherSample()
から参照できません。

必要に応じて、
変数や関数を参照可能な位置へ移動します。

原因6：クラスや関数を削除・移動した

リファクタリングなどでクラスや関数を削除した場合や、
別のパッケージへ移動した場合にも
Unresolved reference
が発生します。

以前のパッケージ名を参照するimportが残っていないか確認します。

import com.example.old.SampleClass

クラスを別のパッケージへ移動した場合は、
新しいパッケージに合わせてimportを修正します。

原因7：別モジュールのクラスを参照できていない

複数モジュールで構成されたAndroidプロジェクトでは、
別のモジュールに存在するクラスを使用するために、
モジュール間の依存関係が必要になる場合があります。

たとえば、
appモジュールから
samplelibraryモジュールを使用する場合は、
次のような依存関係を追加します。

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

モジュール自体がプロジェクトに存在していても、
必要な依存関係が設定されていなければ、
そのモジュール内のクラスを参照できません。

原因8：RがUnresolved referenceになる

Androidアプリでは、
次のようなエラーが発生することがあります。

Unresolved reference: R

Rは、
Androidのリソースを参照するために生成されるクラスです。

Rが参照できない場合は、
Kotlinコード自体ではなく、
XMLリソースなどのエラーが原因になっていることがあります。

resフォルダ内のXMLファイルにエラーがないか、
リソース名が正しいか、
ビルド時に別のエラーが先に発生していないか確認します。

間違ったRをimportしていないか確認する

Rに関するエラーでは、
意図しない
Rクラスをimportしていないかも確認します。

たとえば、
コードのimport部分を確認し、
アプリのリソースではない
Rが追加されていないか確認します。

不要なimportがある場合は削除し、
プロジェクトの正しいリソースを参照するようにします。

原因9：リソース名が存在しない

R自体は認識されていても、
指定したリソース名だけが
Unresolved reference
になる場合があります。

R.id.sampleButton

この場合は、
sampleButton
というIDが実際にXML内で定義されているか確認します。

android:id="@+id/sampleButton"

リソース名のスペルや大文字・小文字、
使用しているレイアウトファイルなども確認します。

原因10：BuildConfigがUnresolved referenceになる

Androidプロジェクトでは、
次のようなエラーが発生する場合があります。

Unresolved reference: BuildConfig

BuildConfigは、
ビルド時に生成されるクラスです。

使用しているモジュールやAndroid Gradle Pluginの設定によっては、
BuildConfigの生成設定を確認する必要があります。

必要な場合は、
Androidモジュールの設定で
buildConfigが有効になっているか確認します。

android {
    buildFeatures {
        buildConfig = true
    }
}

また、
別モジュールの
BuildConfig
を誤って参照していないかも確認します。

原因11：拡張関数の依存関係やimportが不足している

Kotlinでは、
拡張関数として提供されているAPIを使用することがあります。

たとえば、
AndroidXのKTXライブラリなどで提供される機能は、
必要な依存関係やimportが存在しないと
Unresolved reference
になります。

クラス自体は認識されているのに、
特定の関数やプロパティだけが認識されない場合は、
そのAPIがどのライブラリで提供されているのか確認します。

lifecycleScopeがUnresolved referenceになる場合

Android開発では、
次のようなエラーが発生することがあります。

Unresolved reference: lifecycleScope

この場合は、
Lifecycle関連の必要なKTX依存関係やimportが設定されているか確認します。

また、
lifecycleScope
を使用しているクラスが、
対応するLifecycleを持つクラスであるかも確認します。

viewModelsがUnresolved referenceになる場合

次のようなコードで
viewModels
が認識されない場合があります。

private val viewModel: SampleViewModel by viewModels()

この場合は、
使用しているActivityやFragmentに対応したKTXライブラリ、
必要なimport、
依存関係などを確認します。

同じ名前のAPIでも、
使用しているクラスやライブラリによって利用条件が異なる場合があります。

原因12：Kotlinやライブラリのバージョンに互換性がない

Kotlin、
Android Gradle Plugin、
または使用しているライブラリのバージョンに互換性がない場合、
本来使用できるはずのAPIが正常に認識されないことがあります。

ライブラリを更新した直後や、
Kotlin、Gradle、Android Gradle Pluginなどを更新した直後に
エラーが発生した場合は、
バージョンの組み合わせを確認します。

使用しているライブラリの公式ドキュメントなどを確認し、
対応するバージョンの組み合わせを使用します。

原因13：debugやreleaseなどのソースセットが異なる

Androidプロジェクトでは、
main以外に
debug、
release、
Product Flavorなどのソースセットを使用できます。

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

あるクラスが
debugにだけ存在している場合、
releaseビルドからそのクラスを参照することはできません。

特定のビルドバリアントだけで
Unresolved reference
が発生する場合は、
クラスが配置されているソースセットを確認します。

原因14：生成されるコードが作成されていない

ライブラリやビルドツールによって生成されるクラスを使用している場合、
コード生成処理が正常に完了していないことで
Unresolved reference
が発生することがあります。

この場合は、
Build Outputを確認し、
Unresolved referenceより前に
コード生成やGradleタスクに関する別のエラーが発生していないか確認します。

原因15：JavaとKotlin間の参照に問題がある

JavaとKotlinを混在させているプロジェクトでは、
Java側のクラスやメソッドをKotlinから参照するときに
名前やアクセス範囲の問題が発生することがあります。

対象のクラスやメソッドが
privateになっていないか、
正しいパッケージに存在しているか、
Kotlin側から参照可能な状態になっているか確認します。

Gradle Syncで解消するか確認する

ライブラリの追加や変更を行ったあとに
Unresolved reference
が表示された場合は、
まずGradle Syncを実行します。

Gradleの同期に失敗している場合は、
Sync時に表示されているエラーを先に修正します。

Syncが正常に完了したあと、
再度対象のコードを確認します。

CleanやRebuildを実行する

コードや依存関係を修正しても表示が残っている場合は、
古いビルド結果や中間ファイルが影響している可能性があります。

Android Studioの
Buildメニューから、
使用しているAndroid Studioのバージョンで利用可能な
CleanやRebuildに相当する処理を実行します。

その後、
再度ビルドしてエラーが解消されたか確認します。

Android Studio上だけ赤字になる場合

実際のGradleビルドは成功するにもかかわらず、
Android Studioのエディタ上だけ
Unresolved reference
のような赤字表示が残る場合があります。

この場合は、
IDE側のプロジェクト情報とGradleの状態が一致していない可能性があります。

まずGradle Syncを行い、
プロジェクトを再読み込みして状態が更新されるか確認します。

ビルド自体も失敗している場合は、
IDE表示だけの問題として扱わず、
Build Outputに表示されているコンパイルエラーを確認します。

それでもUnresolved referenceが直らない場合

原因が分からない場合は、
エラーになっている名前を基準に順番に確認します。

大量のUnresolved referenceが表示される場合

1つのファイルやプロジェクト全体に、
多数の
Unresolved reference
が同時に表示されることがあります。

この場合、
すべてを個別に修正する必要があるとは限りません。

たとえば、
1つのライブラリが読み込まれていない場合、
そのライブラリに含まれる多数のクラスや関数が
まとめて
Unresolved reference
になります。

また、
Rの生成に失敗している場合は、
多数のリソース参照が一度にエラーになることがあります。

まとめ

Android Studioの
Unresolved referenceは、
Kotlinコンパイラがコード内で指定されたクラス、
変数、
関数、
プロパティなどを見つけられない場合に発生するエラーです。

主な原因として、
スペルミス、
import不足、
Gradle依存関係の不足、
ライブラリのAPI変更、
スコープの問題、
モジュール間依存関係、
ソースセットの違いなどがあります。

Rや
BuildConfigなど、
Androidのビルド時に生成されるクラスが認識されない場合は、
生成元となる設定やリソースに別のエラーが発生していないかも確認します。

大量の
Unresolved reference
が同時に発生している場合は、
それぞれを個別に修正するのではなく、
Gradle Sync、
ライブラリ、
リソース、
コード生成などの共通原因を先に確認します。