---
title: "Troubleshooting"
description: "Troubleshooting for Code Push"
---

This page covers the most common issues with Shorebird Code Push. Still stuck? Reach out on [Discord](https://discord.gg/shorebird) or [file an issue](https://github.com/shorebirdtech/shorebird/issues). The Shorebird team is happy to help.

## Patch not showing up

[Section titled “Patch not showing up”](#patch-not-showing-up)

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 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](https://console.shorebird.dev) to ensure that this release exists for the given app ID and that it has a patch. Please reach out on Discord if such a patch exists and is not being applied.

Common issues:

**The app is running in Debug or Profile mode.**

Shorebird updates are only compiled into and active in **Release builds** of your application. When you run your app in Debug or Profile mode (e.g., via `flutter run`), the Shorebird updater is completely disabled, and standard Flutter JIT or AOT engines are used. Ensure you test updates using a release build (e.g., generated via `shorebird release` or tested via `shorebird preview`).

**You are testing on an iOS Simulator.**

Shorebird patches are not supported on iOS Simulators. Shorebird’s iOS engine uses a custom interpreter designed specifically for physical arm64 iOS devices to comply with Apple’s security sandbox. Because of this, Shorebird updates cannot run on iOS Simulators (which run on x86*64 or arm64 macOS JIT/interpreter architectures). You must use a physical iOS device to test iOS patches. Android emulators \_are* fully supported.

**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 [the iOS releasing guide](/flutter-concepts/releasing-flutter-apps/ios/) 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.

**The app’s process is still running because of a foreground service.**

If the app runs a foreground service or other long-running background work, swiping it from the recent-apps list does not kill the process. Shorebird loads the patch on the next process start.

**How to tell if this is the problem**

The process ID does not change when you swipe the app away. Run `adb shell pidof <your.package.name>` before and after swiping: if it prints the same PID both times, the process never died and no patch will be applied.

From Dart, the equivalent signal is `checkForUpdate()` returning `UpdateStatus.restartRequired`, or `readNextPatch()` reporting a higher patch number than `readCurrentPatch()`.

**How to fix it**

Force-stop the app, or stop the service first, then relaunch. See [How do you use Shorebird with a long-running Android background process?](/code-push/faq/#how-do-you-use-shorebird-with-a-long-running-android-background-process).

## `Your app contains asset changes` warning when creating a patch

[Section titled “Your app contains asset changes warning when creating a patch”](#your-app-contains-asset-changes-warning-when-creating-a-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](https://github.com/shorebirdtech/shorebird/issues/318) 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 anyway? (y/N)
```

So what does this mean? In this case, it means you added a new image to your app. The warning is because your 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 [asset patching](https://github.com/shorebirdtech/shorebird/issues/318) is added.

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.

**What happens if you 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](/code-push/guides/staging-patches) and test locally before deploying it to users.

## `Your app contains native changes` warning when creating a patch, even though you haven’t changed Swift/Objective-C/Kotlin/Java code

[Section titled “Your app contains native changes warning when creating a patch, even though you haven’t changed Swift/Objective-C/Kotlin/Java code”](#your-app-contains-native-changes-warning-when-creating-a-patch-even-though-you-havent-changed-swiftobjective-ckotlinjava-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; the Shorebird team is 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 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 have upgraded to a newer version of Xcode since building the release, you can download older versions of Xcode from [Apple’s developer downloads page](https://developer.apple.com/download/all/).

4. (iOS only) You are building with an old version of Xcode. Specifically, this warning has been seen 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. Shorebird has implemented some safeguards to make this less likely, but it is worth verifying if you are seeing this warning and you do not know why.

**What happens if you 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](/code-push/guides/staging-patches) 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.

## Shorebird fails to install

[Section titled “Shorebird fails to install”](#shorebird-fails-to-install)

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.

## Can’t run your app in VS Code

[Section titled “Can’t run your app in VS Code”](#cant-run-your-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”

[Section titled “Could not find an option named “dart define””](#could-not-find-an-option-named-dart-define)

This typically happens on Windows when using the `--` separator. PowerShell handles the `--` separator differently than other shells (see [this StackOverflow answer](https://stackoverflow.com/a/15788023) for more info). To work around this, you can quote the `--` separator. For example:

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

## Your iOS build number is auto incrementing

[Section titled “Your iOS build number is auto incrementing”](#your-ios-build-number-is-auto-incrementing)

This is likely because you are providing an ExportOptions.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 ExportOptions.plist file.

## Invalid Podfile file

[Section titled “Invalid Podfile file”](#invalid-podfile-file)

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

[Section titled “Unsupported class file major version 65”](#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](https://docs.gradle.org/current/userguide/compatibility.html) to check which Java version works with which Gradle release.

* [Android Studio](https://developer.android.com/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](https://github.com/actions/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.

## Missing a provisioning profile or no signing team was found

[Section titled “Missing a provisioning profile or no signing team was found”](#missing-a-provisioning-profile-or-no-signing-team-was-found)

This issue is addressed in the [releasing guide](/code-push/release). Take a look at the iOS section for more information.

## Message saying patch might run slowly

[Section titled “Message saying patch might run slowly”](#message-saying-patch-might-run-slowly)

iOS uses a very different patching process than Android does. The details of which are described in [System Architecture](/code-push/system-architecture/). This is also discussed in the [Patch Performance](/code-push/performance/) page.

See [Sending a patch-debug.zip to Shorebird](#sending-a-patch-debugzip-to-shorebird) if you are asked for one.

***

## Sending a patch-debug.zip to Shorebird

[Section titled “Sending a patch-debug.zip to Shorebird”](#sending-a-patch-debugzip-to-shorebird)

`shorebird patch ios` writes `build/patch-debug.zip` when it [links](/code-push/system-architecture#how-shorebird-code-push-works) the patch against its release. Send it with any report of a slow patch or a low shared-code percentage.

### When it is produced

[Section titled “When it is produced”](#when-it-is-produced)

Every `shorebird patch ios` run writes one. Android patches do not use the linker and do not produce one.

Shorebird names it in the patch summary only when the link percentage is below 90%:

```
🔍 Debug Info: build/patch-debug.zip
```

Even if you did not see that line, the file is still there.

### Where to find it

[Section titled “Where to find it”](#where-to-find-it)

`build/patch-debug.zip`, relative to your project root. Codemagic respects `$CM_EXPORT_DIR`, so it also shows up in your build artifacts there. On other CI providers, archive it before the runner is torn down.

### What is inside

[Section titled “What is inside”](#what-is-inside)

The compiled Dart snapshots from both sides of the link, plus the link metadata Shorebird uses to compute the shared-code percentage. That is enough to reproduce the link and identify which code was not shared, without access to your project.

Note

`patch-debug.zip` contains your app’s compiled Dart code. It is only partially compiled and names may not be obfuscated, so treat it as more sensitive than the binary you ship publicly, though less sensitive than your source. It contains no Shorebird credentials.

### How to send it

[Section titled “How to send it”](#how-to-send-it)

Send your app ID, the release version, and the file.

A [GitHub issue](https://github.com/shorebirdtech/shorebird/issues) is usually easiest, and a public upload is fine for most apps. For a private app, use [Discord](https://discord.gg/shorebird), <contact@shorebird.dev>, or your shared Slack channel if you are an enterprise customer.

***

## Resolving persistent compile or build failures

[Section titled “Resolving persistent compile or build failures”](#resolving-persistent-compile-or-build-failures)

If you encounter persistent compilation issues or strange env errors that standard builds do not trigger, the local compilation state or tool caches might be corrupted. You can clear all cached build states and tools to start fresh:

1. **Verify environment health**:

   ```
   shorebird doctor
   ```

2. **Clean standard build directories**:

   ```
   flutter clean
   ```

3. **Clean the Shorebird tools cache**:

   ```
   shorebird cache clean
   ```

4. Re-run your release or patch command.

***

## Shorebird commands fail with network/TLS connection errors behind a proxy

[Section titled “Shorebird commands fail with network/TLS connection errors behind a proxy”](#shorebird-commands-fail-with-networktls-connection-errors-behind-a-proxy)

If your development machine or CI/CD runner is situated behind a corporate proxy or firewall, Shorebird CLI commands may fail to connect to Shorebird servers, showing timeout or TLS handshake errors.

To resolve this:

1. **Configure proxy environment variables**: Ensure that standard CLI proxy environment variables are set up in your terminal session:

   * **macOS/Linux**:

     ```
     export HTTP_PROXY="http://your-proxy-server:port"
     export HTTPS_PROXY="http://your-proxy-server:port"
     export NO_PROXY="localhost,127.0.0.1"
     ```

   * **Windows (PowerShell)**:

     ```
     $env:HTTP_PROXY="http://your-proxy-server:port"
     $env:HTTPS_PROXY="http://your-proxy-server:port"
     $env:NO_PROXY="localhost,127.0.0.1"
     ```

2. **Whitelist Shorebird domains**: Ensure your company firewall allows outbound HTTPS traffic (on port `443`) to the following domains:

   * `api.shorebird.dev` (Management API)
   * `download.shorebird.dev` (Engine and CLI downloads)
   * `console.shorebird.dev` (Console interface)

***

## Patch download size is unexpectedly large

[Section titled “Patch download size is unexpectedly large”](#patch-download-size-is-unexpectedly-large)

Shorebird patches are usually small (a few hundred KB) because they only download the binary diff (patch artifact) of your compiled Dart code compared to the release version. If a patch size is unexpectedly large (several MBs):

1. **Upgraded dependencies**: Adding or upgrading large third-party packages in your `pubspec.yaml` can significantly change your compilation graph, causing a cascading code change that results in a larger diff.
2. **Code generators**: Extensive updates to code generation tools (e.g., `build_runner`, `freezed`, `json_serializable`) may modify large amounts of boilerplate code across dozens of files, resulting in a larger binary diff.
3. **Obfuscation configuration mismatch**: Ensure that you have not modified your obfuscation settings (passing/omitting `--obfuscate`) between the release build and the patch build. A mismatch in obfuscation config shuffles class and method names, causing the diff calculation to result in a massive file. Shorebird automatically detects release obfuscation, so you should not add or remove the `--obfuscate` flag when patching.