Maaz Zindani

Loading the index…

↑↓ move↵ openesc close4072 pages

Help for owners

My app broke after updating packages

Short answer

Packages follow version rules, and a major version change signals a breaking change. An update that pulls in a new major version can break the app even when nobody touched your own code. Ask for the update to be reverted to the saved lock file, then update one package at a time with testing.

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

Does this sound like your situation?

  • The app worked until someone updated the packages.
  • The build fails with errors about conflicting versions.
  • The app builds but a screen or feature stops working.
  • Nobody can tell which package caused it.
  • A security warning pushed me to update and now it is broken.

Why does this happen?

  1. A new major version can be a breaking change

    Dart's package rules expect semantic versioning, where a major version increase signals a breaking change. Updating across one can need code changes.

  2. Version ranges allow movement

    A package declares a range of versions it accepts, and the tool picks the most recent that satisfies all constraints. Two packages that need different versions of a shared one can conflict.

  3. The lock file records what worked

    The lock file stores the exact version of every direct and transitive dependency, and pub does not change it until told to. If it was lost or overwritten, the last working set is lost too.

  4. Updating everything at once hides the cause

    Flutter's upgrade page offers commands to update packages and to list outdated ones. Using the broadest update turns one problem into many.

What can I do about it today?

  1. Ask for the last working lock fileIf the project is in version control, the previous version of the lock file is the quickest way back.
  2. Do not update more packagesEach extra update makes it harder to see which change broke the app.
  3. Write down what was updatedThe list of packages and versions before and after is gold for a developer.
  4. Keep the broken build away from customersIf it has not been released, hold the release. If it has, tell your developer immediately.
  5. Separate security from convenienceIf the update was for a security warning, say so. It affects how fast the fix has to be.

When should I bring someone in?

  • The broken version is live.
  • Nobody knows what the app depended on before.
  • A security fix requires the update.

How do I handle it?

  1. Return to a known working setI restore the saved versions and confirm the app builds and runs.
  2. Update in small groupsI update packages one at a time or in related pairs, testing after each.
  3. Read the change notesFor every major version change I read the package's own notes and change the code that depends on it.
  4. Record the resultI leave a clear list of versions and a note on why any package is held back.

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?

Is it safe to skip updates altogether?

No. Old packages can carry known security problems and stop working with new tools, so updates should be small and regular.

Can I fix it by installing the old version?

Often yes, if the exact versions were saved in the lock file. A developer should do it.

How do I avoid this next time?

Update in small steps, keep the lock file in version control and test before each release.

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.