Troubleshooting

Most problems look the same from the outside: you published a patch and nothing changed. Work through these in order.

"I published a patch and nothing changed"

1. Did you fully restart the app?

Patches apply on a cold start. Open the app once so it downloads the patch, swipe it away in the app switcher, and open it again. Going to the background and back isn't a restart.

2. Is the device running the release you patched?

A patch only reaches devices running the exact release it was built for. overpush patch targets the newest release on your computer, so if you built another release after uploading to the store, the patch went to that one. The console's Devices tab shows the release each device runs; patch that one by its id:

$ overpush patch android --release-version 1.4.0+31
$ overpush patch ios --release-version 1.4.0+31

3. Was the release built with OverPush?

A build from plain flutter build appbundle or flutter build apk can't be patched. Rebuild it with overpush release android.

A build from plain flutter build ipa, or from Xcode's Product → Archive, can't be patched. Rebuild it with overpush release ios.

4. Is the device inside the rollout?

At 10% rollout, 9 out of 10 devices correctly get nothing. Raise it with overpush patches rollout <n> --percent 100 while testing.

5. Did the patch number go backwards?

Devices only move to a higher patch number. If a test device already has patch 6 and you publish something as patch 4, it's ignored. Let the CLI choose the number.

6. Did the device roll the patch back?

If the patch crashed on startup, and again on its second try, the device dropped it and won't try that patch again. The dashboard shows the rollback and the error. Fix the bug and publish a new patch.

7. Is the app using the right package?

Run flutter pub deps | grep overpush and check that the version is current. An old dependency_overrides entry or a stale lock file can pin an incompatible version.

White screen after a patch

This usually means the patch was built with a different Flutter version than the release. If you see this:

  1. Revoke the patch: overpush patches revoke <n>.
  2. Run overpush releases info <release> to see whether the release can still be patched.
  3. If it can't, ship a new store release.
  4. If it can, update to the latest CLI and contact support with the --verbose output.

"No signing certificate iOS Distribution" or "PLA Update available"

The release is built and recorded; only Xcode's export to an IPA failed. "PLA Update available" means Apple has a new Developer Program agreement: the account holder must accept it at developer.apple.com before anything can be uploaded. Then open the build with overpush distribute ios and click Distribute App; Xcode signs it for the App Store itself, so no distribution certificate is needed on your Mac.

"The phone has your app signed with a different key"

Shown by overpush preview android when the phone already has your app from the Play Store. Uninstall it from the phone, or keep your release key in android/key.properties (Flutter's standard setup) so previews are signed the same way.

"Install canceled by user"

Xiaomi, Redmi and some other phones ask on screen before installing over USB. Keep the phone unlocked and tap Install, or turn on Install via USB in developer options.

Play Console: "Version code has already been used"

Every upload needs a higher versionCode than the last one. Raise it (the number after + in pubspec.yaml, unless your Gradle file sets it), run overpush release android again, and upload the new .aab.

"This patch uses icons the release does not include"

This release kept only the Material and Cupertino icons its own code used: it was built with CLI 1.2.11 or 1.2.12, or with keep_all_icons: false. Icon fonts ship inside the app, not in a patch, so when a patch uses an icon the release doesn't have, overpush patch stops and lists the icons instead of letting them show as empty boxes on phones.

A new icon shows as an empty box after a patch

The release was built with a CLI older than 1.2.1, so it only carries the icons its own code used. Use icons the release already showed, or update the CLI and ship a new store release.

Windows: "this and base files have different roots"

The project and the pub cache are on different drives (for example D:\ and C:\), and Kotlin's build cache can't handle that. Update the CLI: from 1.2.13 it builds around this by itself. Plain flutter build still fails the same way; add kotlin.incremental=false to android/gradle.properties for those builds.

"Native code changed since the release"

Something in android/ changed, often because a plugin update or Android Studio rewrote a Gradle file. Patches can't carry native code. Either undo the native change, or ship a store release. Use --allow-native-diffs only if you're sure the change doesn't matter at runtime.

Something in ios/ changed, often because pod install or a plugin update rewrote a file. Patches can't carry native code. Either undo the native change, or ship a store release. Use --allow-native-diffs only if you're sure the change doesn't matter at runtime.

"Patch is too large"

The change is too big to send as one patch. Ship it as a store release.

"Publishing is paused" or "Recording a release is paused"

The organization's shipping is paused: an invoice is overdue, or the Hobby plan's patch installs for the month are used up. The message says which, and links to the organization's Billing page in the console. Apps already installed keep working and keep their patches. See Plans and billing.

"CI tokens are part of Pro and up"

A CI runner (a key in OVERPUSH_TOKEN) can publish on Pro and up. On Hobby, run the command from a laptop that is logged in, or upgrade the organization.

CLI not found after installing

Open a new terminal window. The installer updates your shell's PATH, and only new terminal windows pick that up.

Still stuck?

Run the command again with --verbose and send the output to support@overpush.in.