Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

Help for owners

My app stopped building after a Flutter upgrade

Short answer

Flutter publishes breaking changes with every release, and an upgrade can break code that worked before. The official advice is to read the migration guide for the release, run the automated fixer, and update packages. Do not keep upgrading to chase the error. Ask a developer to return to the last version that worked, then upgrade in a controlled way.

  • Written for business owners
  • Updated
  • By Maaz Zindani, Senior Software Engineer

Does this sound like your situation?

  • My developer upgraded Flutter and now the app does not build.
  • The app builds but screens look or behave differently.
  • Error messages mention plugins, Gradle or Kotlin after the upgrade.
  • A release that was ready is now stuck.
  • Nobody remembers which Flutter version the app used before.

Why does this happen?

  1. Each release documents breaking changes

    Flutter keeps a list of migration guides per release for code that must change when a breaking change lands. An app written for an older release can need edits to run on a newer one.

  2. Old APIs are deprecated and then removed

    The migration list shows a pattern: an API is deprecated in one release, and a later release removes it. Code that still uses the removed API stops compiling.

  3. Packages have to be updated too

    Flutter's upgrade page tells you to update dependencies after upgrading and offers commands that list outdated packages. A package that was not updated can fail against the new SDK.

  4. The upgrade moved to a newer version than planned

    The upgrade command takes the latest SDK on your current channel. Running it casually can move a working project forward without anyone choosing the version.

What can I do about it today?

  1. Stop upgradingEach further upgrade can add new errors on top of the old ones. Pause until someone has read the first error.
  2. Find the last version that workedCheck old build logs, release notes or the project files for the Flutter version used at the last good release.
  3. Keep a copy of the project as it isAsk for the code to be saved with its current state before anyone changes it. That keeps a way back.
  4. Do not publish a build made in a hurryA rushed build can introduce new bugs in front of customers. Fix first, release after testing.
  5. Send the first error onlyThe first error in the build output matters most. Later errors are often side effects.

When should I bring someone in?

  • A store release or a fix for your customers is blocked.
  • Your developer is guessing between versions.
  • The project has no record of which version it was built with.

How do I handle it?

  1. Return to a known good stateI restore the version that last built and confirm the app runs, so there is a safe baseline.
  2. Read the migration guides for each release crossedI go through the official guides between the old and new version and list what must change.
  3. Upgrade in stepsI move forward in small steps, fixing and testing at each one, and update the packages that block the way.
  4. Test the real flowsI run the screens your customers use, and then prepare the release with you.

The price depends on what I find, so I quote in writing after a short discovery call. Tell me what is happening and I reply within 24 hours.

What do owners ask about this?

Can the upgrade be undone?

Flutter's upgrade page describes switching to a specific version by checking it out, so going back is possible. A developer should do it, with a copy of the project saved first.

Does Flutter have an automatic fixer?

Yes. The breaking-changes page says to run dart fix after upgrading, and notes that it can migrate many but not all changes.

Why not just stay on the old version?

You can for a while, but store requirements and packages move forward. A planned upgrade is safer than a forced one.

Sources

How was this page made?

I drafted this page with AI assistance from the official documents listed under Sources. Found a mistake? Tell me.

For your developer: the technical fixes

Next step

Want this off your desk?

Send me a few lines on where things stand. I reply within 24 hours.