FAQ & Troubleshooting

If you have questions not answered here, please ask! Both filing an issue or asking on Discord work.

FAQ

What is the difference between a patch and a release?

We use the term “release” to mean preparing a binary for the app stores. In order to later generate a patch Shorebird needs to know the exact binary that was shipped to the app stores. The shorebird release command is used to prepare a binary for the app stores which includes the Shorebird updater.

We use the term “patch” to mean a binary that can be applied to a release to update it to new code. The shorebird patch command is used to generate a patch from your new local code which is then diffed with the release binary to generate a patch which is then shipped to your users.

We explain more of these terms in Overview.

Can I use Shorebird in my country?

We have not attempted to restrict access to Shorebird from any country.

We recognize that some countries have restrictions on what urls can be accessed from within the country. Shorebird currently uses Google Cloud for hosting, including Google Cloud Storage and Google Cloud Run.

The following URLs are used by Shorebird:

• https://console.shorebird.dev — used to interact with Shorebird’s services via the web.
• https://api.shorebird.dev — used by the shorebird command line tools to interact with the Shorebird servers as well as the Shorebird updater on users’ devices to check for updates.
• https://download.shorebird.dev — used by the shorebird command line tool to download Flutter artifacts for building releases and patches.
• https://storage.googleapis.com — used by the shorebird command line tool to upload and download release and patch artifacts, and by the Shorebird updater on user’s devices to download the patches.
• https://cdn.shorebird.cloud/ — used by the Shorebird updater when downloading patches to a user’s device.

Shorebird also uses Microsoft or Google OAuth login, which have their own required urls for login (e.g. login.microsoftonline.com or oauth.google.com).

All traffic to and from Shorebird servers travels over https (port 443) and is encrypted using standard Transport Security Layer / Secure Sockets Layer (TSL/SSL) protocols.

If all of those URLs are accessible from your country, then Shorebird should work.

If your region requires use of FLUTTER_STORAGE_BASE_URL Shorebird may not work for you at this time as we also use that environment variable as part of our implementation. We have plans to remove this restriction, let us know if this is important to you.

Does Shorebird comply with Play Store guidelines?

Yes.

The Play Store offers two restrictions relating to update tools.

1. Updates must use an interpreter or virtual machine (Shorebird uses the Dart Virtual Machine). https://support.google.com/googleplay/android-developer/answer/9888379?hl=en

    An app distributed via Google Play may not modify, replace, or update itself
    using any method other than Google Play's update mechanism. Likewise, an app
    may not download executable code (such as dex, JAR, .so files) from a
    source other than Google Play. *This restriction does not apply to code
    that runs in a virtual machine or an interpreter* where either provides
    indirect access to Android APIs (such as JavaScript in a webview or
    browser).

    Apps or third-party code, like SDKs, with interpreted languages (JavaScript,
    Python, Lua, etc.) loaded at run time (for example, not packaged with the
    app) must not allow potential violations of Google Play policies.

2. Changes to the app must not be deceptive (e.g. changing the purpose of the app via update). https://support.google.com/googleplay/android-developer/answer/9888077 Please be clear with your users about what you are providing with your application and do not violate their expectations with significant behavioral changes through the use of Shorebird.

Shorebird is designed to be compatible with the Play Store guidelines. However Shorebird is a tool, and as with any tool, can be abused. Deliberately abusing Shorebird to violate Play Store guidelines is in violation of the Shorebird Terms of Service and can result in termination of your account.

Code push services are widely used in the industry (all of the large apps I’m aware of use them) and there are multiple other code push services publicly available (e.g. expo.dev & appcenter.ms). This is a well trodden path.

Microsoft also publishes a guide on how their React Native “codepush” library complies with the app stores: https://github.com/microsoft/react-native-code-push#store-guideline-compliance

Does Shorebird comply with App Store guidelines?

Yes.

Similar to the Play Store, the App Store offers both technical and policy restrictions.

3.3.1b
... interpreted code may be downloaded to an Application but only so long as
such code:
(a) does not change the primary purpose of the Application by providing
features or functionality that are inconsistent with the intended and
advertised purpose of the Application as submitted to the App Store,
(b) does not create a store or storefront for other code or applications, and
(c) does not bypass signing, sandbox, or other security features of the OS.

Shorebird uses a custom Dart interpreter to comply with the interpreter-only restriction for updates on iOS. So long as your application is not engaging in deceptive behavior via updates (e.g. changing the purpose of the app via update), updating via Shorebird (or any other code push solution) is standard industry practice and compliant with App Store guidelines.

Deliberately abusing Shorebird to violate App Store guidelines is in violation of the Shorebird Terms of Service and can result in termination of your account.

Microsoft also publishes a guide on how their react native “codepush” library complies with the app stores: https://github.com/microsoft/react-native-code-push#store-guideline-compliance

What is the roadmap?

We try to keep: https://docs.shorebird.dev/status up to date with the status of the project.

Our project boards are also public an found at: https://github.com/orgs/shorebirdtech/projects

Our team also operates in the public, so you can see what we’re working on at any time. We’re happy to answer any questions you have about our roadmap or priorities via GitHub issues or Discord.

Can I self-host Shorebird?

No. Shorebird has no current plans to offer on-prem, self-host or cloud-prem offerings. We would be happy to discuss with you any and all ways in which we can improve our centrally hosted solution to best match your needs.

Can I use Shorebird with my team?

Yes! The Shorebird free “Hobby” tier only supports a single developer, but all other plans support unlimited developers.

See Organizations for more information.

Does Shorebird store my source code?

No. Shorebird servers never see your source code. When you run shorebird release or shorebird patch the shorebird tool only uploads the same compiled app binary that you send to the app stores. Shorebird servers never store your source code at any time.

See also our privacy policy: https://shorebird.dev/privacy

Can I use Shorebird from my CI system?

Yes. Shorebird is intended to be used from CI systems. We’ve published a guide for GitHub Actions, other CI systems should be similar.

Please don’t hesitate to reach out over GitHub issues or Discord if you encounter any issues.

How does this relate to Firebase Remote Config or Launch Darkly?

Code push allows adding new code / replacing code on the device. Firebase Remote Config and Launch Darkly are both configuration systems. They allow you to change the configuration of your app without having to ship a new version. They are not intended to replace code.

How big of a dependency footprint does this add?

I haven’t measured recently, but I expect the code push library to add less than one megabyte to Flutter apps. flutter build apk --release vs. shorebird build apk --release should give you a rough idea. We know of ways we can make this smaller when that becomes a priority. If size is a blocker for you, please let us know!

Does code push work with large applications?

Yes. There is no limit on the size of the application that can be patched with code push. As noted in Overview, Shorebird can change any Dart code in your application no matter of size.

What can I use Shorebird code push for?

We’ve seen a variety of uses, including:

• Emergency fixes to production apps.
• Shipping bug fixes to users on older versions of your app.
• Shipping constantly (e.g. every hour).

Note that most app stores prohibit shipping code that changes the behavior of the app in a significant way. Please see below for more information.

What can’t we use Shorebird code push for?

As above, Shorebird should not be used to violate app store polices. Please see below for more information.

Also Shorebird does not support changing native code (e.g. Java/Kotlin on Android or Objective-C/Swift on iOS). The tool will warn you during an attempted patch if you have changed native code.

Can I use Shorebird for all my Dart changes?

Shorebird can be used to update any Dart code including pure Dart packages. Note that depending on how you distribute your apps, some store agreements expect feature changes to go through store review. Notably Apple’s App Store requires that an update “does not change the primary purpose of the Application by providing features or functionality that are inconsistent with the intended and advertised purpose of the Application.” Also note that patch sizes correlate with the total amount of Dart changed from the original released app. Each patch is a diff against the released dart code, not a diff to the previous patch.

What does the Shorebird updater store on disk?

The Shorebird updater (included in your application when you build your app with Shorebird) caches the latest downloaded patch in the same cache directory that Flutter uses for caching compiled shaders or compiled Dart code. On Android, this is located in /data/user/0/com.example.app/code_cache/shorebird_updater although the base of that path is provided by the Android system and can change dynamically at runtime. On iOS devices, data is stored under Library/Application Support/shorebird.

Shorebird stores only a few files, one is state.json which contains the state information for the updater. When a patch is downloaded a directory will be created for that patch. These directories contain the inflated copies of the patches, which will be about the same size as the compiled Dart code in your application (e.g. ~10 mb each). There will only be at most 2 patches downloaded on the device at a given time. When a new patch is successfully installed and launched, the previous patch is deleted.

What do the Shorebird tools store on disk?

The Shorebird command line tools (e.g. shorebird patch) are installed on disk in $HOME/.shorebird, including bringing a copy of Flutter and Dart as well as the Shorebird release tools themselves. This is similar to how the flutter command works.

These copies of Flutter can be 100s of megabytes each. Shorebird will keep a copy of Flutter $HOME/.shorebird/bin/cache/ for each version of Flutter you have used. Currently this number is unbounded. These can be removed at any time with shorebird cache clear.

Uninstall has details on how to remove Shorebird from your system should you choose.

How does this relate to Flutter Hot Reload?

Flutter’s Hot reload is a development-time-only feature. Code push is for production.

Hot reload is a feature of Flutter that allows you to change code on the device during development. It requires building the Flutter engine with a debug-mode Dart VM which includes a just-in-time (JIT) Dart compiler.

Code push is a feature that allows you to change code on the device in production. We will use a variety of different techniques to make this possible depending on the platform. Current demos execute ahead-of-time compiled Dart code and do not require a JIT Dart compiler.

Does Shorebird support Flutter Web?

Code push isn’t needed for Flutter web. When a user opens a web app it downloads the latest version from the server if needed.

If you have a use case for code push with Fluter web, we’d love to know!

What platforms does Shorebird support?

Shorebird supports iOS and Android today. We plan to support all other Flutter platforms over time.

Use of Shorebird on each platform is an independent decision. For example You can use shorebird release to ship to Google Play and an ipa built with flutter build to the App Store or vice versa.

Shorebird can (relatively easily) be made to support desktop or embedded targets. If those are important to you, please let us know.

What OS versions does Shorebird support?

Shorebird supports the same versions of Android that Flutter supports.

Flutter currently supports Android API level 21+ and iOS 16.0+: https://docs.flutter.dev/reference/supported-platforms

What versions of Flutter does Shorebird support?

Android is supported on Flutter 3.10.0 or later.

iOS is supported on Flutter 3.16.9 or later.

See https://docs.shorebird.dev/flutter-version for more information.

Shorebird tracks Flutter stable and generally updates within a few hours of any stable release. Our system for doing these updates is automated takes a few minutes to run. We then do an extra manual verification step before publishing to our servers.

Does code push require the internet to work?

Yes. One could imagine running a server to distribute the updates separately from the general internet, but some form of network connectivity is required to transport updates to the devices.

How is Shorebird affected by lack of network connectivity?

Shorebird updater (included in your application when you build your app with Shorebird) is designed to be resilient to network connectivity issues.

In the default update behavior, when the application launches it alerts the Shorebird updater, which spawns a separate thread to make a network request to Shorebird’s servers and ask for an update. We intentionally use a separate thread to avoid affecting blocking anything else the application might be doing. If the network request fails or times out, the updater will simply try to check again next time the application launches.

Shorebird command line tools (e.g. shorebird patch) require network connectivity to function. If you are using Shorebird to distribute your app, you should ensure that your CI system has network connectivity.

What happens if a user doesn’t update for a long time?

A user will always get the latest patch available for their version of the app, regardless of which patch (if any) they currently have installed. A patch will always reflect the state of the codebase at the time when the patch was built so as long as newer patches also contain the changes from older patches, users will always be up to date and there is no need to worry about users “missing” patches.

How does Shorebird relate to Flutter?

Shorebird is a fork of Flutter that adds code push. Shorebird is not a replacement for Flutter, but rather a replacement for the Flutter engine. You can continue to use the Flutter tooling you already know and love.

shorebird uses a fork of Flutter that includes the Shorebird updater. We track the latest stable release of Flutter and replace a few of the Flutter engine files with our modified copies.

To implement our fork, we use FLUTTER_STORAGE_BASE_URL to point to https://download.shorebird.dev instead of download.flutter.dev. We pass through unmodified output from the flutter tool so you will see a warning from Flutter:

Flutter assets will be downloaded from http://download.shorebird.dev. Make sure you trust this source!

For more information about why we had to fork Flutter see System Architecture.

When do updates happen?

By default, the Shorebird updater checks for updates on app startup. It runs on a background thread and does not block the UI thread. Any updates will be installed while the user is using the app and will be applied the next time the app is restarted.

It is also possible to run the Shorebird updater manually using package:shorebird_code_push, through which it is possible to trigger updates at any time, including via a push notification.

See update-strategies for more information about how to configure this behavior.

Do I need to keep my app_id secret?

No. The app_id is included in your app and is safe to be public. You can check it into version control (even publicly) and not worry about someone else accessing it.

Someone who has your app_id can fetch the latest version of your app from Shorebird servers, but they cannot push updates to your app or access any other aspect of your Shorebird account.

Can I use Dart defines with Shorebird?

Yes. The shorebird command line tool passes through all Dart defines to the flutter tool. For example, shorebird release android -- --dart-define=MY_DEFINE=foo and shorebird release android -- --dart-define-from-file=config.json will both work as expected. Because Dart defines are compiled into your app’s Dart code, they can be updated via patches.

What information is sent to Shorebird servers?

Although Shorebird connects to the network, it does not send any personally identifiable information. Including Shorebird should not affect your declarations for the Play Store or App Store.

See also our privacy policy: https://shorebird.dev/privacy

Requests sent from the app to Shorebird servers include:

• app_id (specified shorebird.yaml)
• channel (optional in shorebird.yaml)
• release_version (versionName from AndroidManifest.xml)
• patch_number (generated as part of shorebird patch android)
• arch (e.g. ‘aarch64’, needed to send down the right patch)
• platform (e.g. ‘android’, needed to send down the right patch)

That’s it. The code for this is in: https://github.com/shorebirdtech/updater/blob/main/library/src/network.rs

How does Shorebird interact with Play Testing Tracks or Apple TestFlight?

Each of the app stores have separate mechanisms for distributing apps to limited groups of users (e.g. “internal testing”, “closed beta”, etc.). These are all mechanisms for segmenting your users into groups and distributing specific versions of your apps to each.

Unfortunately, these not all of these mechanisms allow 3rd parties to detect when apps are installed in any specific Test Track or via TestFlight. Thus, we do not have reliable visibility into composition of these groups, and cannot reliably gate access to Shorebird patches based on these groups. https://stackoverflow.com/questions/53291007/can-an-android-application-identify-the-test-track-within-google-play https://stackoverflow.com/questions/26081543/how-to-tell-at-runtime-whether-an-ios-app-is-running-through-a-testflight-beta-i

If you’d like to segment availability of Shorebird patches, there are 4 potential options:

1. Use separate binaries / bundle ids for each group. This is the most straightforward approach, but requires you to manage multiple binaries. On Android the easy way to accomplish this is through flavors. You may already have a dev flavor and prod flavor with different availability. You can thus patch your dev flavor, verify it and then separately patch your prod flavor. We recommend using branches / tags in your version control to help keep track of the sources associated with each release.
2. Track your own set of opt-in users, disable automatic updates, and trigger updates only for certain users via package:shorebird_code_push. This works today, but requires you to manage your own opt-in list.
3. Shorebird could create its own opt-in mechanism on a per-device basis (similar to Test Tracks or TestFlight, just platform agnostic). This could allow your QA team to opt-in to patches before they’re promoted to the general public. If this is important to you, please let us know: https://github.com/shorebirdtech/shorebird/issues/498
4. Shorebird plans to add percentage based rollouts. This does not let you choose which devices to send to, but can help you roll out incrementally and roll-back on sight of any problems. https://github.com/shorebirdtech/shorebird/issues/497

Will my app still work if I cancel my Shorebird subscription?

Yes. Apps built with Shorebird will continue to function normally (as if they had been built without Shorebird), including those that have had patches installed.

Now that I’m using Shorebird, do I still need to send my app to the stores?

Yes. We recommend customers continue to release their app through the stores in addition to using Shorebird. Even if this now means that there can be less pressure on your app release process.

This is for two reasons:

1. Stores have policy restrictions that “major new features” go through store review to avoid “deceiving users”. Since apps are likely to change over time, periodic releases (to update store screenshots, etc.) is still good practice.
2. New users install from the stores, not Shorebird. Shorebird can only update your application after launch, so for users to get the best first-launch experience, we recommend that you continue to periodic releases to the stores.

Does Shorebird submit to the stores for me?

Shorebird does not currently support submitting to the app stores on your behalf. We have plans to add this in the future, but for now you will need to continue to use your existing processes to submit to the app stores. https://github.com/shorebirdtech/shorebird/issues/257

When should I create a patch vs a release?

Because patching and releasing are independent operations, it is possible to create both a patch and a release with the same code changes.

Note

A “release” gets a unique release version, while a “patch” does not change the release version, just the “patch number”. The “release version” is a store concept, where as “patch number” is a Shorebird concept. Apps can read the current patch version at runtime via the package:shorebird_code_push.

Different customers have used different policies to decide whether to create a release, a patch, or both. I’ll enumerate a few of these here:

1. Push a patch immediately to update all existing users, while also simultaneously submitting a release to the stores so that new users to their product will get the latest code on first launch after a store install.

2. Use patching as a mechanism to ship changes on a high frequency (e.g. daily or weekly) and only go through a full release process on a lower cadence (e.g. monthly).

3. Continue to only use releases for shipping code changes, and only patch to fix critical bugs or make other emergency changes.

In the end, it comes down to what works for your business. We see most of our current customers choosing option 2.

Note

Changes which involve native code cannot be patched and thus must use a release for distribution.

Do I need to distribute my app through a store?

No. Shorebird can be used with any app distribution method, including side-loading or carrier provided stores.

Shorebird is not itself a store. Your users will need to install your app initially through some method other than Shorebird, but Shorebird can then be used to patch (update) your app after that initial install.

Billing

How do I upgrade or downgrade my plan?

To upgrade your plan, you can subscribe via the Shorebird console.

To cancel your subscription, you can view your account and click “Edit” -> “Cancel Subscription”.

When does my billing period reset?

Billing periods are reset automatically every month on the month you first subscribed to Shorebird. For example, if you subscribed on the 15th of the month, your billing period will reset on the 15th of every month.

How do I cancel my subscription?

To cancel your subscription, you can view your account and click “Edit” -> “Cancel Subscription”.

You will continue to have all the features of a paid account until the end of your billing period.

Can I pay for a year in advance?

Currently we have not yet implemented yearly billing. We don’t expect it will be hard, we just aren’t quite sure what customers expect in terms of overage charges on a yearly plan. If you have thoughts on this, please let us know: https://github.com/shorebirdtech/shorebird/issues/733

What counts as a “patch install” for Shorebird?

A “patch install” is counted when a patch is successfully installed on a user’s device.

I created a patch, but it’s not showing up in my app

Your first step in debugging should be to check your app’s logs. Instructions for this can be found at https://shorebird.dev/blog/viewing-logs/.

You should see logs prefixed with [shorebird]. If you do not see [shorebird] in your logs, the app you are running was not built using shorebird release and cannot receive patches. You will need to redistribute your app using a binary created by shorebird release.

If you do see Shorebird in your logs, you’ll want to look for a a line that includes the patch check request being made. It looks like:

Sending patch check request: PatchCheckRequest {
  app_id: "<your app id>",
  channel: "stable",
  release_version: "1.0.3+16", <-- this is the release version
  patch_number: <some patch number>,
  platform: "android",
  arch: "aarch64"
}

If the release version is the version you expect to see, check the Shorebird Console to ensure that this release exists for the given app id and that it has a patch. Please contact us on Discord if such a patch exists and is not being applied.

Common issues:

The patch was created for a different release version than the one running on your device/emulator.

Patches are only compatible with the release version they were created for. If you create a patch for version 1.0.0+1, it will not work on version 1.0.0+2.

Note

This can happen unexpectedly on iOS due to Xcode’s automatic incrementing of build numbers. If you are seeing this issue on iOS, ensure that the build number of the release and the patch match. See our iOS releasing guide for instructions on how to disable automatic build number incrementing.

How to tell if this is the problem

You will see Shorebird updater: no active patch in your device logs.

How to fix it

Ensure that the version of your app on your device/emulator matches the version of the release you patched. You can see what release version your app is running by looking in the device logs for a patch check request:

Sending patch check request: PatchCheckRequest {
  app_id: "<your app id>",
  channel: "stable",
  release_version: "1.0.3+16", <-- this is the release version
  patch_number: <some patch number>,
  platform: "android",
  arch: "aarch64"
}

Only patches created for this release version will be compatible with your app.

I installed Shorebird, and now I can’t run my app in VS Code

If you see error output like the following when using the Run or Debug button in VS Code:

FAILURE: Build failed with an exception.

* What went wrong:
Execution failed for task ':app:checkDebugAarMetadata'.
> Could not resolve all files for configuration ':app:debugRuntimeClasspath'.
   > Could not find io.flutter:arm64_v8a_debug:1.0.0-4a5e8142f3e7368a48e4f6151cb7b1a684d6dd83.
     Searched in the following locations:

It’s possible that VS Code is incorrectly using Shorebird’s version of Flutter instead of the Flutter on your path (see https://github.com/Dart-Code/Dart-Code/issues/4607). You can fix this by explicitly providing VS Code with the path to your Flutter installation. In your settings.json file, add the line:

"dart.flutterSdkPath": "/path/to/flutter"

Where “/path/to/flutter” is the path to your Flutter installation. You can get this by running which flutter in your terminal (or where.exe flutter on Windows) and removing the /bin/flutter from the end of that path.

Could not find an option named “dart define” when using the -- separator

Powershell handles the -- separator differently than other shells (see this StackOverflow answer for more info). To work around this, you can quote the -- separator. For example:

shorebird release android '--' --dart-define=foo=bar

Shorebird fails to install

There are a number of reasons this might happen. Common causes are:

I see a message saying that git stat failed because a file was too long

This can happen on Windows due to Windows’ limit of 260 characters for a filename.

You can fix this by running:

git config --system core.longpaths true

You may need to run this as an administrator, and you will need to restart your terminal after running this command.

My iOS build number increments when I try to make a release or patch

This is likely because you are providing an export options .plist file that sets manageAppVersionAndBuildNumber to true. This is incompatible with Shorebird because Shorebird requires that you maintain control over your app’s version and build numbers in order to target patches at specific releases. You can fix this problem by either setting manageAppVersionAndBuildNumber to false or removing the value from your export options .plist file.

I see a Your app contains asset changes warning when running shorebird patch

The shorebird patch command will print a warning if it detects changes to files in your compiled app that correspond to asset changes (e.g. added or removed images, fonts, etc.). This does not always mean that your patch will not work, but shorebird cannot be sure that the changes are safe.

Shorebird does not (yet) have the ability to patch assets but intends to add such in the future, at which time this warning may go away.

An example of this warning:

✓ Verifying patch can be applied to release (4.0s)
[WARN] The release artifact contains asset changes, which will not be included in the patch.
    Added files:
        base/assets/flutter_assets/assets/images/bg_button_disable.png
    Changed files:
        base/assets/flutter_assets/AssetManifest.bin
        base/assets/flutter_assets/AssetManifest.json
        base/assets/flutter_assets/fonts/MaterialIcons-Regular.otf
Continue anyways? (y/N)

So what does this mean? In this case, it means I added a new image to my app. The warning is because my patched Dart code could depend on those new assets which will not be present when the patch is applied in the wild. It can be safe to ignore this kind of warning if you’re removing an asset that is not used by your code, or your Dart code knows how to handle the asset being missing.

Also included in the above changes are the AssetManifest files. These files change any time you add or remove an asset from your app, and are generally a symptom rather than the cause of the warning.

The final file changed above is the MaterialIcons-Regular.otf font file, which can happen if your app uses more or fewer icons from the Dart code. Flutter will automatically “tree shake” your fonts, so if you don’t use an icon in your Dart code, it will not be included in the final app. You can disable this behavior with --no-tree-shake-icons at the risk of increasing your app size. This type of warning will also go away once we add [https://github.com/shorebirdtech/shorebird/issues/318](asset patching).

A type of change not shown above is one which changes .dex files on Android or the Runner.app directory on iOS. These changes represent changes to the native code of your app, and are not patchable by Shorebird. If you see this warning, you should be very careful about publishing your patch, as it may cause your app to crash when the Dart code tries to call into native code which operates differently than expected. See the next section.

What happens if I ignore this warning?

You can bypass this warning by passing the --allow-asset-diffs flag to the shorebird patch command.

The consequences of ignoring this warning depend on the changes that were made. In the tree-shaking example above, if you ignore the warning, your app will render incorrectly if you use an icon that was not included in the release build. Any assets introduced in a patch will fail to load and your app may crash if it depends on them.

If you are not sure whether your change is safe, you can stage your patch and test locally before deploying it to users.

I see a Your app contains native changes warning when running shorebird patch, even though I haven’t changed Swift/Objective-C/Kotlin/Java code

The shorebird patch command will print a warning if it detects changes to files in your compiled app that correspond to native code changes (.dex files on Android, files in the Runner.app directory on iOS). This does not always mean that your patch will not work, but because shorebird cannot be sure that the changes are safe, and because shorebird can’t patch non-Dart code, it prints a warning.

Note

Shorebird assumes a repeatable build — if you build the application twice it ends up byte-for-byte identical (with a few minor known exceptions, like the certificate signing date for iOS apps). Some Flutter Plugins or obfuscation solutions violate this assumption and can cause these native changes to appear. Shorebird may be incompatible with those plugins. You can test for this by doing a shorebird release and then shorebird patch with no changes and seeing if you still get a native changes warning. If you believe this is the case please reach out to us, we’d be happy to help!

This can be caused by a number of things. The most common causes are:

1. A dependency/plugin you are using has changed its native code. You should use caution when publishing patches that include changes to native code from plugins. In the worst case, these changes may cause your patched app to crash.

   Tip

   Add your pubspec.lock file to version control so you’re always aware of updates to your dependencies.

   Versioning your pubspec.lock file ensures changes to transitive dependencies are explicit. Each time the dependencies change due to dart pub upgrade or a change in pubspec.yaml, the difference will be apparent in the lock file.

2. A dependency/plugin produces a different output on every build. This can happen if the dependency it includes a timestamp indicating when it was built, for example. This kind of change is usually safe to publish, but you should be sure this is the only reason you are seeing this warning.

3. (iOS only) The release was built with a different version of Xcode than the patch. This can be fixed by ensuring that you are using the same version of Xcode to build the release and the patch. If you’ve upgraded to a newer version of Xcode since building the release, you can download older versions of Xcode from Apple’s developer downloads page.

4. (iOS only) You are building with an old version of Xcode. Specifically, we’ve seen this warning when building with Xcode 14.1. If you are using a version of Xcode that is not the latest, try upgrading to the latest version.

5. The version and build number of the patch do not match that of the release. For example, if the release was built with version 1.0.0+1, but the patch was generated with version 1.0.0+2, you might see this warning. We have implemented some safeguards to make this less likely, but it’s worth verifying if you’re seeing this warning and you don’t know why.

What happens if I ignore this warning?

Danger

If the changes are to native code that interacts with your Flutter app or with Flutter itself, your app will crash.

If the native code that changed does not interact with your Dart code or Flutter at all, the patch should run without issue.

If you are not sure whether your change is safe, you can stage your patch and test locally before deploying it to users.

If you are sure the changes are safe, you can bypass this warning by passing the --allow-native-diffs flag to the shorebird patch command.

”Invalid Podfile file: cannot load such file” when running pod install

You might see this error message if the FLUTTER_ROOT definition in your project’s ios/Flutter/Generated.xcconfig points to a Shorebird Flutter installation. This can be fixed by running any of:

1. flutter clean, or
2. flutter build ios in your project’s root directory, or
3. flutter run in your project’s root directory and targeting an iOS simulator/device.

Unsupported class file major version 65

The error Unsupported class file major version 65 (or 66—the number varies sometimes) happens when gradle is being executed with an incompatible Java version.

You can check the specific Gradle version that your app is using by running shorebird doctor -v inside the project folder. This command will also print the java version that shorebird is using.

Refer to the official Gradle documentation to check which Java version works with which Gradle release.

• Android Studio comes with a bundled JDK which should be auto detected by Shorebird and might be the easiest way of solving the issue.
• If in a GitHub Action, the setup-java action can help.
• Or try Installing the required Java version for your project’s Gradle release and set the path where it was installed in the JAVA_HOME environment variable.

When creating an iOS release, I see an error saying that I’m missing a provisioning profile or that no signing team was found.

We address this issue in our releasing guide. Take a look at the iOS section for more information.

When creating an iOS release, I see an error that the patch might run slowly.

iOS uses a very different patching process than Android does. The details of which are described in Architecture docs.

Notably iOS attempts to re-use as much code from the original release as possible when creating a patch. “Linking” in Shorebird terms is the process of deciding which code in the original release is possible to re-use after applying this patch, vs when we need to use an interpreter (slower) for the new patched code.

Because very little of a Flutter app is typically your code (the vast majority of any Flutter app is usually the Flutter Framework itself), any patch should be able to share the majority of code with the release. Almost always above 80%.

If you’re seeing a warning about the patch potentially running slowly please reach out to us over Discord or email and included the mentioned patch_debug.zip file.

“Running slowly” means that some percentage of your Dart code will end up executing within Shorebird’s interpreter (significantly slower than executing compiled code on the CPU), which could result in parts of your app feeling 2x-3x slower.

Link errors like this are not your fault, nor is there really any action that a developer can take to avoid them. They just represent edge-cases where our linker got confused about whether it could re-use a function in the release and took the conservative path of not, resulting in this low link percentage and warning. Your app, including the patch you just made, remains 100% safe to use, it may just run slower with the patch applied. You can of course always stage the patch or test the patch before distributing to users and if you encounter any complaints roll back the patch.

The patch_debug.zip file contains debugging information relating to the linking process. We do not upload this file by default as it contains un-obfuscated class and function names (which while generally harmless, some customers are sensitive about sharing). The files included in the .zip are in the most part plain text and you should feel free to read them should you desire.