Flutterのビルドエラーの調べ方|flutter doctorから始めるエラー解決の順番

このページには広告が含まれる場合があります。

 

※この記事は、2026年11月10日に、Flutter・Dart・Gradleの公式ドキュメントで確かめた内容です(Flutterの公式ドキュメントは、この時点でFlutter 3.47を前提に書かれています)。コマンドの出力やメニューの名前は、バージョンや環境によって異なります。

「昨日まで普通に動いていたのに、今日はビルドが通らない」

「赤い文字が何十行も出てきて、どこを読めばいいのかわからない」

「エラー文をそのまま検索しても、出てくる記事が古くて、自分の状況に合わない」

Flutterのビルドエラーで止まると、「なんでやねん、何もしてへんのに!?」と言いたくなりますよね。

先に答えを書くと、ビルドエラーは、いきなり検索するより、次の順番で調べていくと、どこで止まっているのかが見えてきます。

  1. flutter doctor で、開発環境そのものに問題がないかを見る
  2. 長いエラーの中から、「最初の原因」が書かれた行を探す
  3. 直前に何を変えたか(Flutter・Android Studio・Xcode・パッケージの更新)を思い出す
  4. flutter clean と flutter pub get で、ビルドの残りを片付けてからやり直す
  5. エラー文の「人によって変わらない部分」で検索し、公式やGitHubのissueを見る

ぼくがプログラミングを始めたのは、金融の会社を辞めたあとのアラフォーのころで、まったくの未経験でした。本のとおりに打ったつもりでも、カンマ1つの抜けや、ハイフンとアンダースコアの違いで動かない。そういうエラーに限って、検索しても出てこない。聞ける人もいませんでした。あとから考えるとしょうもないことでも、出くわしたときは、地獄に落ちたような気分だったんです。

今は、自社アプリ6タイトル・12本を、どれもFlutterで作っています。他社や受講生のアプリの開発支援まで含めると、リリースの実績は30本以上です。

ここからは、上の順番に沿って、1つずつ見ていきます。

 

1. まずはflutter doctorで、環境に問題がないかを見る

まずは公式の情報から見ていきます。

ビルドエラーの原因は、自分のコードやプロジェクトの設定だけとは限りません。FlutterのSDK、AndroidのSDKやライセンス、Javaなど、開発環境のほうがずれていることもあります。

そこで最初に打つのが、このコマンドです。

flutter doctor

Flutterの公式のコマンド一覧では、flutter doctor は「入っている開発ツールの情報を表示する」コマンドとされています。

結果は、項目ごとに並んで出てきます。公式の困ったときのページの例では、次のように、問題のある項目に [!] が付き、その下に X で中身が出ています。

[!] Android toolchain - develop for Android devices (Android SDK version 33.0.2)
    X cmdline-tools component is missing

印の付いた行が、最初の手がかりです。

もっと詳しく見たいときは、-v を付けます。

flutter doctor -v

公式の困ったときのページでも、書いてある手順を試しても直らないときは、flutter doctor -v で詳しいログを出して、コミュニティで助けを求めるように書かれています。人に相談するときも、このログを一緒に渡すと、話が早くなります。

flutter doctorでよく出るもの

公式の困ったときのページに載っているものから、Androidまわりの3つを挙げておきます。

  • Androidのライセンスが「unknown」と出る

flutter doctor --android-licenses を実行し、ライセンスごとに y を入れて承認します。そのあと、もう一度 flutter doctor で確かめます。

  • 「cmdline-tools component is missing」と出る

いちばん簡単なのは、Android StudioのSDK Managerから入れる方法だと書かれています。Android Studioを使っていない場合は、sdkmanagerというコマンドラインのツールで入れます。

  • Javaが何種類も入っていて、--android-licenses が失敗する

古いJDK(Javaの開発キット)が入っていると起きる、とされています。複数のJavaが要らないなら、今あるJDKをアンインストールすると、FlutterはAndroid Studioに入っているJDKを自動で使います。

(ライセンスのエラーは、2023年に個別の記事でも書いています。画面は今と違う所がありますが、流れの参考になると思います)

flutter doctorで印が付かなくても、ビルドが通らないことはあります。 そのときは、環境ではなく、プロジェクトの側を疑って、次に進みます。

参考:Troubleshooting installation・flutter: The Flutter command-line tool(いずれもFlutter docs、2026年11月10日確認)

 

2. 長いエラーは、「最初の原因」の行を探す

エラーが出ると、画面が赤い文字で埋まります。でも、全部の行が同じ重さではありません。

読むのは、「何が起きたか」が書かれた最初の行です。 そのあとに続く行は、その結果として出ていることがよくあります。

どこを見ればいいかは、どこでビルドが止まったかで変わります。

Android(Gradle)で止まったとき

Androidのビルドを受け持っているのは、Gradleというツールです。Gradleの公式の説明では、ビルドが失敗すると、出力の中の「What went wrong」の所に、エラーのメッセージが出ます。

* What went wrong:
Execution failed for task ':app:...'.

(上は形の例です。タスクの名前やメッセージは、エラーによって変わります)

メッセージが「Execution failed for task」で始まっていたら、どれかのタスク(ビルドの中の作業の1つ)を実行している途中で失敗した、という意味です。その下の行に、何がだめだったのかの中身が続きます。

それでもわからないときのために、Gradleの公式では、次のオプションが紹介されています。

  • --stacktrace(-s):エラーが起きた場所までの流れ(スタックトレース)を出す。公式では、まずこれを使うように勧めています
  • --info・--debug:ログを細かくして、失敗の前に何が起きていたかを見る。ただし --debug は出力がとても大きく、見られたくない情報が出ることもある、と注意書きがあります

これらは、Gradleを直接動かすときに付けるオプションです。Flutterのプロジェクトでは android フォルダの中で使うことになります(動かし方は環境によって異なります)。

Flutterのコマンドの側からは、-v(--verbose)を付けると、ログが詳しくなります。

flutter run -v

Flutterのコマンドの説明では、-v は「実行したシェルのコマンドまで含めた、詳しいログ」を出すもの、とされています。どのコマンドの途中で止まったのかを追いたいときに使えます。

参考:Troubleshooting builds(Gradle User Manual、2026年11月10日確認)/flutter_command_runner.dart(Flutterのソースコード、2026年11月10日確認)

iOS(Xcode・CocoaPods)で止まったとき

ターミナルのログだけではわかりにくいときは、Xcodeでもプロジェクトを開いてみます。

Flutterの公式ドキュメントでは、Xcodeで開くのは ios/Runner.xcworkspace とされています。ターミナルなら、Flutterのプロジェクトのフォルダで次のコマンドを打つと開けます。

open ios/Runner.xcworkspace

iOSのビルドでは、CocoaPods(iOS側のパッケージを入れる仕組み)の pod install で止まることもあります。

(pod install で止まったときの例は、こちらの記事でも書いていますので、よろしければご覧ください)

参考:Build and release an iOS app(Flutter docs、2026年11月10日確認)

Dartのコードで止まったとき

AndroidやiOSの設定ではなく、自分の書いたDartのコードでビルドが止まることもあります。

エラーには、大きく分けて、文法のエラー・実行時のエラー・論理のエラーの3つがあります。このうち、ビルドの段階で止まるのは、主に文法のエラーです(実行時と論理のエラーは、ビルドが通って動かしたあとに出てきます)。

もう1つ、覚えておくと落ち着けることがあります。「deprecated(非推奨)」の警告は、エラーではありません。アプリは動きます。急がずに、あとで落ち着いて書き換えれば大丈夫です。

 

3. 直前に何を変えたかを思い出す

「昨日まで動いていた」のなら、その間に何かが変わっています。よくあるのは、次のようなものです。

  • flutter upgrade で、Flutterを上げた
  • Android Studio、Xcode、macOSを上げた(Flutterを上げていなくても、Android Studioを上げただけで、裏で使うJavaの設定がずれることがあります)
  • パッケージを足した、または flutter pub upgrade で上げた

今のFlutterのバージョンは、次のコマンドで確かめられます。公式のコマンド一覧では、フレームワーク・エンジン・ツールを含めた今のFlutter SDKのバージョンがわかる、とされています。

flutter --version

Flutterを上げたあとにエラーが出たなら、公式の「Breaking changes(破壊的変更)」のページを見ます。Flutterの破壊的変更のお知らせと、移行のしかたのガイドが集められています。

パッケージを上げたあとなら、そのパッケージのCHANGELOG(変更履歴)を見ます。公式どおりに書いたはずのコードが非推奨やエラーになるときは、だいたいここに理由が書いてあります。

偉そうに書いていますが、ぼくも講座で教えていたころは、Flutterの更新でRaisedButtonがなくなり、教材をElevatedButtonに一生懸命直したことがあります。Flutterは、書き方がよく変わる道具なんです。

(Android Studioを上げたら、GradleとJavaのバージョンが合わなくなった例は、2024年にこちらの記事で書いています)

参考:flutter: The Flutter command-line tool・Breaking changes and migration guides(いずれもFlutter docs、2026年11月10日確認)

 

4. ビルドの残りを片付けてから、もう一度ビルドする

原因の見当がついても、前のビルドの残りが悪さをしていて、直したのに同じエラーが出続けることがあります。そのときに使うのが flutter clean です。

flutter clean
flutter pub get

公式のコマンド一覧では、flutter clean は「build/ と .dart_tool/ のフォルダを消す」コマンドです。消したあとは、flutter pub get でパッケージを入れ直してから、もう一度ビルドします。

flutter clean は、何でも直す魔法ではありません。 消すのはビルドの途中でできたものなので、コードや設定の間違いは残ったままです。次のビルドは、一から作り直すぶん時間もかかります。「直したはずなのに変わらない」ときの片付け、くらいに考えておくのがちょうどいいと思います。

ちなみに、講座で教えていたとき(2025年1月)に flutter clean を実演したら、945MBあったプロジェクトが32MBくらいになりました。プロジェクトをためていくと、「パソコンのストレージを知らない間にシロアリが食い潰すような感じ」でなくなっていくので、使っていないプロジェクトの片付けにも使えます。

参考:flutter: The Flutter command-line tool(Flutter docs、2026年11月10日確認)

パッケージどうしのバージョンが合わないとき

パッケージを足したとたんにエラーになるなら、パッケージどうしのバージョンの組み合わせを疑います。

Flutterのプロジェクトでは、次のコマンドで、パッケージのバージョンの一覧が出ます。

flutter pub outdated

Dartの公式の説明では、一覧の列は次の意味です。

列意味
Current今使っているバージョン(pubspec.lock に記録されているもの)
Upgradablepubspec.yaml の指定で上げられる、いちばん新しいバージョン
Resolvableほかのパッケージとの組み合わせを考えたうえで、上げられるいちばん新しいバージョン
Latest公開されている、いちばん新しいバージョン(プレリリースは除く)

「Latest」まで上げたいのに「Resolvable」が低いままなら、ほかのパッケージとの組み合わせが、それ以上上げるのを止めている、ということです。

参考:dart pub outdated(dart.dev、2026年11月10日確認)

 

5. エラー文で検索するときのコツ

ここまでやって、まだ原因がわからなければ、いよいよ検索です。そのときは、次の4つを意識すると、合う情報に当たりやすくなります。

  1. 人によって変わる部分を外す

自分のフォルダの名前、プロジェクトの名前、行の番号などを外し、エラー文の変わらない部分だけで検索します。完全に同じ文で探したいときは、" で囲みます。

  1. 英語のまま検索する

日本語に訳すと、同じエラーの話でも見つけにくくなります。

  1. 記事の日付と、そのときのバージョンを見る

Flutterの世界は変わるのが速く、昔の対処法が今は要らないことも、かえって逆効果のこともあります。このサイトにも、あとで「解消済」と付けた記事がいくつもあります。

  1. パッケージのエラーなら、そのパッケージのGitHubのissueを見る

同じエラーで困った人の報告と、直し方の話し合いが見つかることがあります。公式の困ったときのページでも、新しく質問を立てる前に、似た話がないかを探すように書かれています。

AIに聞くときは、答えを自分で動かして確かめる

エラー文をAIに聞くのも、今は当たり前の手です。ぼくも2025年ごろは、エラーが出るとGrokにエラーコードを入れて聞いていました。

ただ、AIはもっともらしい答えを返してきます。2025年3月に、iOSの通知の不具合をGrokに聞いたら、それらしい答えと出典のリンクが返ってきました。開いてみたら、「ページが見つかりません」。「Grok もウソつくよ」というのが、そのときの実感です。

講座で教えていたとき(2024年12月)も、ChatGPTの説明を読んで、そのまま信じずにDartPadで動かして確かめていました。そのときに口に出していたのが、「こうやってもっともらしく嘘つくときがあるから、やってみよう」という一言です。

AIは、何を使ってもいいと思っています。ただ、AIが出した直し方の意味を、自分で説明できることが大事です。 意味がわからないまま直すと、次に同じところで止まったときに、自分で直せないからです。

 

人に相談するときに、そろえておくもの

自分で調べても止まったままなら、人に聞くのも立派な手です。そのときに次のものがそろっていると、聞かれた側も原因を追いやすくなります。

  • いつ、何をしたら、エラーが出たか(直前に変えたことも)
  • エラーメッセージの全文と、エラーの状況がわかるスクリーンショット
  • FlutterとDartのバージョン(flutter --version の結果)
  • flutter doctor -v の結果
  • 実際に動かして確かめるための、プロジェクトのデータ(ZIPやGitHubのリポジトリ)

これは、ぼくがビルドエラーの相談を受けるときにお願いしている情報とほぼ同じです。

 

ビルドエラーで手が止まっている方へ

ここまでの順番で調べても、どの行が本当の原因なのかを、ひとりで見極めるのは意外と難しいですよね。特に、AndroidとiOSの設定、パッケージの組み合わせが絡むと、どこから手を付けていいかわからなくなります。

ぼくのFlutterビルドエラー解決(Zoom・60分)では、Zoomの画面共有で、エラーをリアルタイムに一緒に確かめながら、解決を目指します。Gradle・CocoaPods・パッケージの依存関係などのエラーに対応していて、解決策の説明と、同じエラーを繰り返さないためのアドバイスもお伝えします。60分で解決しきれなかった場合も、原因の特定と、この先の対処法をご案内します。よろしければ、お気軽にご相談ください。

 

まとめ

参考:Troubleshooting installation・flutter: The Flutter command-line tool・Build and release an iOS app・Breaking changes and migration guides(いずれもFlutter docs、2026年11月10日確認)/Troubleshooting builds(Gradle User Manual、2026年11月10日確認)/dart pub outdated(dart.dev、2026年11月10日確認)

何かのお役に立てれば幸いです。

  • Flutterのビルドエラーは、いきなり検索するより、順番に調べた方が、どこで止まっているかが見えてくる
  • 最初は flutter doctor。印の付いた行が手がかり。詳しく見るなら flutter doctor -v
  • 長いエラーは、「何が起きたか」が書かれた最初の行を読む。Gradleなら「What went wrong」の所
  • Gradleは --stacktrace で、Flutterは -v で、ログを詳しくできる
  • iOSは、Xcodeで ios/Runner.xcworkspace を開いて確かめる
  • deprecated(非推奨)の警告は、エラーではない
  • 「昨日まで動いていた」なら、Flutter・Android Studio・Xcode・パッケージのどれを上げたかを思い出す。Flutterを上げたなら公式の破壊的変更のページ、パッケージならCHANGELOGを見る
  • flutter clean は、build/ と .dart_tool/ を消して片付けるもの。そのあと flutter pub get を忘れずに。何でも直す魔法ではない
  • パッケージの組み合わせは flutter pub outdated で、Current・Upgradable・Resolvable・Latestを見比べる
  • 検索は、人によって変わる部分を外して英語のまま。記事の日付とバージョンも見る
  • AIの答えは、自分で動かして確かめ、意味を説明できるようにしてから使う

アプリのリリースでお困りですか?
Google Play・App Storeへのリリース支援サービスをご用意しています。
ビルドエラー解決・動作確認・申請代行まで、現役開発者が対応します。

みんプロ式・アプリ開発支援サービス一覧を見る ↗

こんな記事も読まれています

TOP