The Flutter errors that cost me hours (and how to fix them in minutes)

Gibberish always has a cause

When you build with Claude Code and do not know Flutter, error messages are scary. Good news: every error has a precise cause, and the fix often takes two minutes. The real problem is knowing which one.

Here are the ones I hit most often.

Setup and environment

• "Android license status unknown": Android Studio is installed but its licenses were never accepted. Run flutter doctor --android-licenses and answer "y" to everything.
• "flutter: command not found": Flutter is not in your PATH. Add the flutter/bin folder to your .zshrc file, then reload the terminal.
• "CocoaPods not installed": Flutter needs CocoaPods for iOS. Install it with Homebrew, then run pod install in the ios folder.

Flutter and Dart

• "RenderFlex overflowed by X pixels": content is bigger than the space available, often a Column inside a parent that does not scroll. Wrap it in a SingleChildScrollView. My rule: beyond 3 or 4 children, I plan for it.
• "setState() called after dispose()": an async operation finished after the screen was closed. Check that the widget is still mounted before updating. Long term, a state manager like Riverpod avoids the problem.
• "Null check operator used on a null value": an exclamation mark was used on an empty value. My rule: never use the exclamation mark, always plan a default value.
• "MissingPluginException": a native plugin is not linked. The universal fix: flutter clean, flutter pub get, pod install, then run again.

iOS and Xcode

• "Signing requires a development team": open the .xcworkspace file (not the .xcodeproj), pick your team in Signing & Capabilities and enable automatic signing.
• "Archive failed": run Clean Build Folder. If it still fails, delete Pods and Podfile.lock, run pod install again, then rebuild.
• Apple rejection for a missing description: if the app uses the camera, photos or location, Info.plist must explain why. Generic sentences are rejected: Apple wants to know why your app needs it.

Android and Gradle

• "minSdkVersion 16 cannot be smaller than 21": raise the minimum version to 21 in the app's build.gradle file.
• "Unsupported class file major version": your Java version does not match Gradle. Set a recent Gradle version in gradle-wrapper.properties.

Publishing on the App Store

• "Missing Export Compliance": Apple asks whether the app uses encryption. If you only use HTTPS, declare it in Info.plist with the ITSAppUsesNonExemptEncryption key set to false.
• A build that crashes at archive time: in 80% of cases, flutter clean then pod install fixes it.

The rule for every error

Before searching for two hours, paste the full error message into Claude Code, not just the last line, and ask for the cause before the fix. If it cannot find it, give it context: the command you ran, what you had just changed.

All these errors, and many more, are collected in the "error bible" of the [ByNeel Starter Kit](/kit).