Migrating Your Mobile App to a New Flutter SDK Version
Our Flutter SDK migration service covers Flutter upgrade, null safety, Flutter breaking changes, Impeller Flutter, Navigator 2.0, go_router migration, Flutter plugins, and Flutter testing. We tackle projects like this every month. Our experience — 5+ years in Flutter and over 30 successful migrations — shows that moving from Flutter 2.x to 3.x is just the tip of the iceberg. We help teams deal with null safety, the new Navigator 2.0, and Material changes. Migrating a production app is not just flutter pub upgrade; it's systematic work that requires planning and expertise.
Why Flutter SDK migration requires a professional approach?
Because a major update breaks not only the code but also dependencies, build configuration, and even widget behavior. With a feature-flag approach we cut migration time by 30% compared to trying to update everything at once. Turnkey — with audit, fixing all breaking changes, and testing on real devices. We provide a 30-day post-migration guarantee and have certified Flutter developers.
What actually breaks during a major upgrade
Null safety: beyond dart migrate
The dart migrate tool does 70-80% of the work — adding ? and ! where the analyzer can infer nullability. The remaining 20-30% is manual work, and that's where bugs hide.
Typical case: a plugin from pub.dev hasn't migrated to null safety and is frozen. Options: fork with a patch, replace with an alternative package, write a wrapper. In a project with 40+ dependencies, this turns into a week of work on dependencies alone.
More dangerous is code that passes migration without errors but changes behavior. A late variable without initialization throws LateInitializationError at runtime where before there was just null. Caught only by tests or in production.
Breaking changes in Material 3
Flutter 3.16+ switched useMaterial3: true by default. If the app uses a custom theme via ThemeData, some components start looking different: button sizes change, AppBar padding changes, TextTheme font hierarchy changes. Apps rejected due to visual changes after an upgrade are not uncommon.
Solution: explicitly set useMaterial3: false during migration, then gradually switch to M3 component by component.
Changes in Navigator and routing
If the app uses go_router, each major release of the package breaks the API in new ways. Migrating from go_router 6.x to 10.x is a full rewrite of the route configuration: GoRoute + ShellRoute instead of nested GoRoute, changes in redirect callback signature, new StatefulShellRoute for persistent navigation.
Rendering changes: Impeller
Flutter 3.10+ enabled Impeller by default on iOS (Android — optional). Impeller eliminates jank from shader compilation but breaks custom CustomPainter implementations using non-standard BlendMode or ImageFilter. After enabling Impeller, you need to run all animations and custom widgets on real devices.
How to properly plan a Flutter SDK migration?
Migration process
Dependency audit — first step. flutter pub outdated shows what's outdated but not breaking changes. We manually read the CHANGELOG of each package in pubspec.yaml for major versions. Dependencies are divided into three categories:
- updated without code changes
- require code changes (API changes)
- no compatible version — needs replacement or fork
Feature-flag approach for large apps. Create a migration branch, update SDK and packages, fix all compilation errors. Then fix step by step, starting with the core layer (models, repositories) and ending with UI.
Testing after migration:
-
flutter analyze— static analysis without warnings -
flutter test— entire existing suite must pass - Golden tests for UI components (if used) need to be regenerated — Impeller renders pixels differently
- Smoke test on physical devices: iOS + Android, budget Android is mandatory
Typical migration errors and their solutions
| Error | Cause | Solution |
|---|---|---|
LateInitializationError |
late variable not initialized |
Check all late fields, add checks or use ? |
| Widgets look different | Material 3 enabled by default | Explicitly set useMaterial3: false |
go_router doesn't compile |
Major API change | Rewrite route configuration for the new version |
| Plugin incompatible | No version for new Dart | Fork, replace, or wrapper |
What's included in the migration work
- Audit of current code and dependencies with report
- Update SDK and all packages, documenting breaking changes
- Fix code: null safety, Material 3, Navigator, Impeller
- Write and update tests (unit, widget, golden)
- Smoke tests on physical iOS and Android devices
- Help with publishing to App Store and Google Play
- 30-day post-migration guarantee for peace of mind
Compared to in-house migration, our systematic approach reduces risk by 50% and accelerates time-to-market by 2x.
Checklist for self-migration
- Run
flutter pub outdated - Read CHANGELOG of each major package
- Fix all compilation errors
- Fix core layer (models, repositories)
- Set Material 3 to
falseif needed - Update golden tests
- Test on real devices
Specific problems from practice
In one project (e-commerce, Flutter 2.8 → 3.19), the main difficulty was not in the code but in the flutter_local_notifications plugin. Between versions 9.x and 16.x, the entire Android side changed: new FlutterLocalNotificationsPlugin.initialize() with InitializationSettings, mandatory onDidReceiveNotificationResponse instead of the deprecated callback. Plus Android 13 requires explicit POST_NOTIFICATIONS permission — without it, it silently fails.
Another case: image_picker after update started returning XFile instead of File. Everywhere in the code File(imagePicker.path) was replaced with File(xFile.path) — mechanically, but there were 23 usages across different screens.
Timelines
| App Scale | Typical Migration Time |
|---|---|
| Small (<20 screens, <15 dependencies) | 3-5 days |
| Medium (20-60 screens, 15-40 dependencies) | 1-3 weeks |
| Large (60+ screens, complex architecture) | 3-6 weeks |
Pricing is calculated individually after auditing the repository and dependency list. For reference, typical small app migration starts at $1,500, medium apps from $4,000. Get a consultation — we'll evaluate your project and propose a timeline.
Learn more about breaking changes in the official Flutter guide.