Roll back a Patch
If you discover that a live patch has a bug, Shorebird supports patch roll back. When a patch is rolled back, it is remotely uninstalled from end users’ devices and replaced by either the previous patch or the base release if no previous patch is available.
A rollback is not permanent. If you roll a patch back and then decide you want it after all, you can roll it forward to make it available to devices again.
If your app saves state to disk, the code that runs after a rollback reads what the rolled-back patch wrote. Shipping BLoC changes as a patch shows how to keep saved state readable in both directions.
If an iOS app crashes once a patch installs, the release’s Flutter version may be the cause; see App crashes after a patch installs.
Active and superseded patches
Section titled “Active and superseded patches”When a device checks in, Shorebird serves the highest-numbered patch on that device’s track that has not been rolled back. This page calls it the active patch. On the release’s page, the Console marks the active patch on each track and platform Latest.
Apart from Deactivate on older releases, patches have no individual on/off switch. Publishing patch 3 outranks patch 2 without any action on patch 2:
- One patch is served per track at a time.
- Lower-numbered patches are superseded: devices aren’t served them while a higher-numbered patch is on the track.
- Rolling back the active patch moves devices to the next-highest patch on the track that has not been rolled back, or to the base release.
The exception is a
percentage rollout. While the
newest patch on a track is offered to only part of its devices, the rest keep
getting the newest patch that’s at 100%, so more than one patch is served at
once. The Console offers Roll back only on the newest; to roll back the
patch the rest of your devices run, use
shorebird patches rollback.
On a release that supports rollback, the Console offers Roll back only on the patch its track serves on that platform (on older releases, see Releases that can’t roll back). A superseded patch gets it once every newer patch on its track and platform is rolled back. To return users to patch 1 while patch 3 is live, roll back patch 3, then roll back patch 2, which now shows Roll back. Leave patch 1 alone.
Releases that can’t roll back
Section titled “Releases that can’t roll back”On a release built with a Flutter version from before rollback support, the
⋮ menu on the patch the stable track serves shows Deactivate instead
of Roll back. New devices stop getting the deactivated patch and get the
newest patch that isn’t deactivated. Devices that already have the patch keep
it, so ship a fixed patch as well.
Why the Console may still show old patches installing
Section titled “Why the Console may still show old patches installing”Patch install events are reported the next time an app launches, which can be hours or days later. A patch that is no longer served can keep showing new install events during that window.
How to roll back a patch
Section titled “How to roll back a patch”In the Shorebird Console, navigate to the release that contains the patch you want to roll back. Only the active patch offers Roll back; on older releases, see Releases that can’t roll back. Open the ⋮ menu of the patch marked Latest on its track (for the affected platform) and select Roll back:

Click Roll back in the dialog to roll the patch back.
Roll back from the rollout card
Section titled “Roll back from the rollout card”The Rolling out card at the top of Mission Control shows the newest live
stable patch on your app’s five newest releases, or a newer release once
devices start running it. When it’s a patch on a release that supports rollback,
the card has a Roll back button that opens the same dialog. Before you click
it, check the patch number and release version on the card. To roll back a patch
the card doesn’t show, open its release.
Once you roll that patch back, the card moves on to the next most recent rollout. That may be another patch, possibly on another release. It has its own Roll back button only if it’s still rolling out.
A week after the patch was created, even if it reached stable later, or once
80% of its release’s active devices have it (when the card shows adoption), the
card shrinks to a Last shipped line without Roll back. Use View
release on that line to roll back from the release’s page.
Roll back from the CLI
Section titled “Roll back from the CLI”As of Shorebird 1.6.120, you can also roll back a patch from the command line. Pass the release version and the patch number:
Shorebird reads the app ID from shorebird.yaml in the current directory. To
run the command from anywhere else, such as a CI job, pass --app-id. If your
app uses flavors, pass --flavor to pick the
right app ID.
If the patch is already rolled back, the command says so and exits successfully.
Add --require-change to make it exit with an error instead, so a script can
tell whether this run changed anything. Add the global --json flag for
machine-readable output:
What happens when a patch is rolled back?
Section titled “What happens when a patch is rolled back?”Imagine a release with two patches:

When a user downloads this release from the store, Shorebird will see that patch 2 is the latest available patch and download it.
If a problem is discovered with patch 2, it can be rolled back. The Console hides rolled back patches by default. With Show rolled back and deactivated turned on next to the Patches heading, it looks like this after a rollback:

Users who download the app from the store will now get patch 1 instead of patch 2. Users who already had patch 2 installed will be downgraded to patch 1.
Under the hood
Section titled “Under the hood”When a Shorebird app checks for new patches, the server includes in its response a list of rolled back patches. If the device has any rolled back patches installed, it deletes them and reverts to the last “good” patch, which will be visible the next time the app starts.
Roll a patch forward
Section titled “Roll a patch forward”Rolling a patch forward is the opposite of rolling it back: it takes a patch you previously rolled back and makes it available to devices again. Use it when you roll back a patch and then determine it was not the cause of the problem, or when you have confirmed the patch is safe after all.
In the Shorebird Console, navigate to the release containing the rolled back patch. Rolled back patches are hidden by default, so turn on Show rolled back and deactivated next to the Patches heading. Open the patch’s ⋮ menu and select Roll forward:

Click Roll forward in the dialog to roll the patch forward.
Roll forward appears only on a rolled back patch, on a release that supports
rollback, with no newer live patch on its track and platform. To roll forward an
older patch without touching the newer one, use
shorebird patches rollforward; the older patch
stays behind the newer one until that is rolled back. On the patch its track
serves, the same menu offers Roll back instead. On a
release that can’t roll back, the patch
stable serves offers Deactivate.
Roll forward from the CLI
Section titled “Roll forward from the CLI”shorebird patches rollforward takes the same arguments as
shorebird patches rollback, including --app-id,
--flavor, --require-change, and --json:
If the patch isn’t rolled back, the command reports that it is already active
(not rolled back) and exits successfully, unless you pass --require-change.
On a protected track, rolling forward files an approval request instead, and the command exits with an error that links to it. Rolling back never needs approval.
What happens when a patch is rolled forward?
Section titled “What happens when a patch is rolled forward?”The patch stops being reported as rolled back, so it becomes the active patch for its track again, unless a newer patch is live there; then nothing changes for devices until that one is rolled back. When it is the active patch, devices download it on their next update check and apply it the next time the app restarts, exactly as they would a newly published patch.
Patch integrity and automatic rollback
Section titled “Patch integrity and automatic rollback”Shorebird includes safety features to prevent needing to issue the manual rollback of a patch.
shorebird patch also generates a hash of your patch file which is stored
separately from the patch and checked when your patch is installed on the user’s
device. With
patch_verification: strict,
signed releases also check it every time the app boots from the patch.
Shorebird also signs patches: releases made
with Shorebird CLI 1.6.132 or later are signed by default with a key Shorebird
manages for your organization, or you can sign with your own key. This uses the
same cryptographic algorithms used in the Google and Apple app stores. A signed
release includes a
public key in your app
bundle, and a patch’s signature is checked on the device before the app runs it
(when depends on your Flutter build and patch_verification),
so your app never accepts a patch that wasn’t signed with the matching private
key, except with install_only on the builds listed in
install_only skips the check on some builds.
Finally Shorebird’s updater includes automatic on-device rollback. If a patch’s hash or signature doesn’t match, the patch is discarded.
If a patch fails to load into the Dart runtime on Android or iOS, the device marks the patch “bad” and never tries to boot it again. Later launches boot the previous working patch still on the device, or your release’s original code if there isn’t one, until a newer patch has downloaded.
What happens on the launch that failed depends on the platform and the Flutter version the release was built with:
- iOS, Flutter 3.47.0 or newer (the default since Shorebird 1.6.118): that launch runs your release’s original code.
- iOS, Flutter 3.47.4 or newer (the default since Shorebird 1.6.122): that
launch also checks for a newer patch if automatic updates are on. With
auto_update: falseinshorebird.yaml, the check happens when your app calls the updater. - Android, and iOS before Flutter 3.47.0: the app closes on that launch, and the device records the failure when the app next starts.
On macOS, Windows and Linux, the same mark-bad behavior needs Flutter 3.47.8 or newer (the default since Shorebird 1.6.133). On older versions, a Windows or Linux app whose patch fails to load doesn’t start, on every launch, until it’s reinstalled. A macOS app runs your release’s original code but keeps the patch and tries it again on every launch.
The previous patch file is always kept on disk until at least one successful boot is made of the next patch, after which a patch file is automatically cleaned up from the user’s device to minimize disk usage.
All code which implements these integrity measures is of course open source and available for review on GitHub. An overview of Shorebird’s code locations is available under System Architecture.