Common Errors
| Symptom | Likely cause | Fix path |
|---|---|---|
| RenderFlex overflow stripes | Row/Column child exceeds constraints | Use flexible layout, scrolling, or responsive breakpoints |
MissingPluginException | Plugin not registered, unsupported platform, hot reload after native change | Full restart, verify platform support, add fallback |
| iOS CocoaPods failure | Native plugin dependency or pod repo issue | Re-run iOS dependency setup on macOS, inspect plugin docs |
| Android Gradle failure | Plugin, SDK, namespace, min/target mismatch | Check plugin Android setup and Gradle config |
| Web build fails after package add | Package uses dart:io, native code, or unsupported APIs | Choose web-supported package or disable feature on web |
| State resets unexpectedly | State stored in widget that gets recreated | Move state to parent, key correctly, or use view model/app state |
| Test passes but app fails on device | Plugin/native path not covered by widget tests | Add integration/manual target smoke |
| Release build behaves differently | Debug-only assumptions, assertions, permissions, tree shaking | Test profile/release modes and release artifact |
| Store upload rejected | Signing, package identity, screenshots, privacy, permission policy | Use target store checklist and fix metadata/policy |
Fast Diagnosis
flutter doctor -v
flutter analyze
flutter test
flutter devices
flutter run -d <target>Record the target, Flutter version, package change, and build mode before changing code.