※この記事は、2026年11月10日に、Flutter・Dart・Gradleの公式ドキュメントで確かめた内容です(Flutterの公式ドキュメントは、この時点でFlutter 3.47を前提に書かれています)。コマンドの出力やメニューの名前は、バージョンや環境によって異なります。
「昨日まで普通に動いていたのに、今日はビルドが通らない」
「赤い文字が何十行も出てきて、どこを読めばいいのかわからない」
「エラー文をそのまま検索しても、出てくる記事が古くて、自分の状況に合わない」
Flutterのビルドエラーで止まると、「なんでやねん、何もしてへんのに!?」と言いたくなりますよね。
先に答えを書くと、ビルドエラーは、いきなり検索するより、次の順番で調べていくと、どこで止まっているのかが見えてきます。
flutter doctorで、開発環境そのものに問題がないかを見る- 長いエラーの中から、「最初の原因」が書かれた行を探す
- 直前に何を変えたか(Flutter・Android Studio・Xcode・パッケージの更新)を思い出す
flutter cleanとflutter pub getで、ビルドの残りを片付けてからやり直す- エラー文の「人によって変わらない部分」で検索し、公式やGitHubのissueを見る
ぼくがプログラミングを始めたのは、金融の会社を辞めたあとのアラフォーのころで、まったくの未経験でした。本のとおりに打ったつもりでも、カンマ1つの抜けや、ハイフンとアンダースコアの違いで動かない。そういうエラーに限って、検索しても出てこない。聞ける人もいませんでした。あとから考えるとしょうもないことでも、出くわしたときは、地獄に落ちたような気分だったんです。

今は、自社アプリ6タイトル・12本を、どれもFlutterで作っています。他社や受講生のアプリの開発支援まで含めると、リリースの実績は30本以上です。
ここからは、上の順番に沿って、1つずつ見ていきます。
もくじ
1. まずはflutter doctorで、環境に問題がないかを見る
まずは公式の情報から見ていきます。
ビルドエラーの原因は、自分のコードやプロジェクトの設定だけとは限りません。FlutterのSDK、AndroidのSDKやライセンス、Javaなど、開発環境のほうがずれていることもあります。
そこで最初に打つのが、このコマンドです。
flutter doctorFlutterの公式のコマンド一覧では、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 -vFlutterのコマンドの説明では、-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.xcworkspaceiOSのビルドでは、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 --versionFlutterを上げたあとにエラーが出たなら、公式の「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 outdatedDartの公式の説明では、一覧の列は次の意味です。
| 列 | 意味 |
|---|---|
| Current | 今使っているバージョン(pubspec.lock に記録されているもの) |
| Upgradable | pubspec.yaml の指定で上げられる、いちばん新しいバージョン |
| Resolvable | ほかのパッケージとの組み合わせを考えたうえで、上げられるいちばん新しいバージョン |
| Latest | 公開されている、いちばん新しいバージョン(プレリリースは除く) |
「Latest」まで上げたいのに「Resolvable」が低いままなら、ほかのパッケージとの組み合わせが、それ以上上げるのを止めている、ということです。
参考:dart pub outdated(dart.dev、2026年11月10日確認)
5. エラー文で検索するときのコツ
ここまでやって、まだ原因がわからなければ、いよいよ検索です。そのときは、次の4つを意識すると、合う情報に当たりやすくなります。
- 人によって変わる部分を外す
自分のフォルダの名前、プロジェクトの名前、行の番号などを外し、エラー文の変わらない部分だけで検索します。完全に同じ文で探したいときは、" で囲みます。
- 英語のまま検索する
日本語に訳すと、同じエラーの話でも見つけにくくなります。
- 記事の日付と、そのときのバージョンを見る
Flutterの世界は変わるのが速く、昔の対処法が今は要らないことも、かえって逆効果のこともあります。このサイトにも、あとで「解消済」と付けた記事がいくつもあります。
- パッケージのエラーなら、そのパッケージの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の答えは、自分で動かして確かめ、意味を説明できるようにしてから使う
ビルドエラー解決・動作確認・申請代行まで、現役開発者が対応します。













