fix: Shorebird patch breaks Flutter Deferred Components (Play Feature Delivery) — DeferredLoadException: program fingerprint mismatch

[Abdan009]

Summary

After applying any shorebird patch android — even patches that only modify base app code — all deferred components fail to load with:

DeferredLoadException: Deferred loading unit is from different program than the main loading unit

This makes Shorebird patches completely incompatible with Flutter Deferred Components that use Play Feature Delivery split APKs.

---

Environment

	Version
Shorebird CLI	shorebird --version 1.6.98
Flutter SDK	flutter --version 3.41.9
Dart SDK	dart --version 3.11.5
Android Gradle Plugin	8.x
Platform	Android
Delivery mechanism	Play Feature Delivery (split APKs via flutter.deferred-components in pubspec.yaml)

---

Steps to Reproduce

Setup:

pubspec.yaml declares deferred components:

flutter:
  deferred-components:
    - name: presence_feature
      libraries:
        - package:presence/presence.dart
    - name: calculator_feature
      libraries:
        - package:calculator/calculator.dart

Dart code uses deferred imports:

import 'package:presence/presence.dart' deferred as presence;

// Triggered on user action:
await presence.loadLibrary();

Reproduce:

1. Run shorebird release android
2. Upload AAB to Play Store (Internal Testing track)
3. Install the app via Play Store — all deferred components load correctly ✅
4. Make any change to base app code (e.g., change a string in lib/main.dart)
5. Run shorebird patch android
6. Open the app — Shorebird patch is applied successfully (Shorebird updater reports patch installed)
7. Trigger any deferred component load (e.g., navigate to a screen that calls loadLibrary())
8. App crashes / throws exception ❌

---

Expected Behavior

Shorebird patch is applied to the main loading unit. Deferred components that were not modified continue to load correctly, since their code has not changed.

---

Actual Behavior

DeferredLoadException: Deferred loading unit is from different program than the main loading unit

All deferred components fail to load, regardless of whether their code was modified in the patch.

---

Root Cause Analysis

How Dart AOT loading unit fingerprinting works

When Dart AOT compiles a Flutter app with deferred components, it produces multiple .so files — one per loading unit:

libapp.so      ← main loading unit (loading unit 0)
libapp-2.so    ← deferred component A
libapp-3.so    ← deferred component B

At compile time, Dart embeds a program fingerprint (a hash derived from the entire compiled program) into every loading unit .so. This fingerprint is used at runtime to verify that all loading units were compiled from the same Dart program:

// Dart runtime check (simplified):
if (deferred_unit.program_fingerprint != main_unit.program_fingerprint) {
  throw DeferredLoadException('Deferred loading unit is from different program...');
}

What Shorebird patch does

shorebird release android compiles all loading units together → all .so files share fingerprint V1. These are uploaded to the Play Store and distributed as split APKs via Play Feature Delivery.

shorebird patch android recompiles and patches only libapp.so (the main loading unit). The patched libapp.so now has fingerprint V2.

However, the deferred component .so files (libapp-2.so, libapp-3.so, etc.) are bundled inside Play Feature Delivery split APKs managed by the Play Store. Shorebird has no mechanism to patch these files. They remain at fingerprint V1.

After shorebird patch:

  libapp.so (Shorebird-patched) → fingerprint: V2
  libapp-3.so (Play Store split) → fingerprint: V1

  V2 ≠ V1 → DeferredLoadException on every loadLibrary() call

Why base-app-only changes still break deferred components

The program fingerprint is computed from the entire compiled program — not just the main loading unit. Any code change, even a single character in lib/main.dart, produces a different fingerprint. This means any Shorebird patch, regardless of what was changed, will cause a fingerprint mismatch with existing deferred component split APKs.

---

Impact

This is a complete incompatibility between two first-class Flutter features:

• Flutter Deferred Components (officially supported, documented at flutter.dev)
• Shorebird code push

Any Flutter app that uses flutter.deferred-components in pubspec.yaml cannot use shorebird patch without breaking all deferred functionality. The only workaround today is to avoid patching altogether and use shorebird release for every update, which eliminates Shorebird's core value proposition.

---

Potential Solutions

For the Shorebird team's consideration:

Option A — Patch all loading units

Extend the Shorebird patch mechanism to also generate and distribute patches for each deferred loading unit .so. The patched deferred .so files would need to be distributed alongside or instead of the Play Feature Delivery split APKs.

Challenges:

• Deferred .so files are currently distributed via Play Feature Delivery, outside Shorebird's control
• Would require a parallel delivery mechanism for patched deferred loading units

Option B — Preserve fingerprint across patches

Investigate whether Dart's fingerprint check can be made version-aware — i.e., the deferred loading unit declares a minimum compatible main unit fingerprint range rather than a single exact fingerprint. This would require changes on the Dart VM side.

Option C — Expose compatibility flag

Expose an API in shorebird_code_push that indicates a patch is active, so apps can gracefully degrade (e.g., skip loadLibrary() and show an "update required" screen) instead of crashing.

This is a partial mitigation rather than a fix, but it would prevent force closes while a full solution is developed.

---

References

• Flutter Deferred Components documentation: https://docs.flutter.dev/perf/deferred-components
• Dart loading unit specification: dart/runtime/vm/dart.cc — DartVM::Init fingerprint verification
• Play Feature Delivery: https://developer.android.com/guide/playcore/feature-delivery

---

Additional Notes

This issue was discovered in a Flutter monorepo using Play Feature Delivery with three deferred components and a custom DeferredComponentManager (required due to the play:core → feature-delivery:2.x migration). The error is reproducible on both physical devices and emulators running Android 10+.

[eseidel]

That's correct. We currently use parts of the deferred loading system for patching.

I'm surprised you're using the deferred loading system? Last I knew it had essentially zero usage in the wild. I'd be very curious to learn more about your usage and how well it's worked for you, if you've seen significant size savings from it, etc.

[Abdan009]

Thanks for the confirmation — and for the context that Shorebird itself
uses the deferred loading system internally. That explains the conflict
at a deeper level than I initially understood.

Happy to share our experience in detail.

---

Flutter's deferred component support has been stagnant

One likely reason for low adoption is that Flutter itself hasn't
meaningfully updated its deferred component implementation in a long
time. The most visible symptom: the latest Flutter still ships with
PlayStoreDeferredComponentManager compiled against
com.google.android.play:core, which Google has deprecated and is
actively removing from Play Store support.

This means anyone trying to use deferred components today on a modern
AGP/Gradle setup will immediately hit a NoSuchMethodError crash —
before they even get to write any feature code. The official Flutter
documentation still points to play:core:1.10.3.

To make it work, we had to implement a custom
CompatDeferredComponentManager in Kotlin (~620 lines) that:

• Implements Flutter's DeferredComponentManager interface directly
• Calls feature-delivery:2.x API instead of the deprecated one
• Handles package replacement after split APK install (Play Store does
  PACKAGE_REMOVED → PACKAGE_REPLACED, which disconnects the
  SplitInstallManager listener for subsequent modules)
• Resolves race conditions between addOnSuccessListener and the
  INSTALLED state callback
• Uses multi-strategy .so loading to handle stale context paths
  after package replacement

In total we worked through 6 bugs before it was stable. The feature
works — but the barrier to entry is very high, which likely explains
why adoption in the wild is low.

---

About the ditonton project specifically

The project referenced in this issue report is a proof-of-concept,
not a production app. We use it specifically to test compatibility
between deferred components and various tools and services we rely on
— Shorebird being one of them.

The deferred modules in that project are intentionally minimal. The
largest split is only ~101 KB. It is a controlled environment for
compatibility testing, not a representation of real-world usage.

---

The actual production use case

The real motivation comes from a larger project: a super app with
many independent features, each built as its own Flutter package with
its own assets.

Feature sizes vary significantly:

• Lightweight utility features: ~1–5 MB
• Heavy features: up to ~80 MB

The upper end comes from features that implement on-device AI
(face recognition and others) — models and native libraries that are
large by nature but only relevant to specific users.

Bundling everything into a single base APK would result in an
unacceptably large initial download. Deferred components — where each
feature module is downloaded only when the user first accesses it —
is the right architectural fit for this problem. Users only pay the
download cost for features they actually use.

---

On Shorebird

We have been using Shorebird in production for some time and have been
very happy with it. The ability to push fixes without going through a
full Play Store review cycle is genuinely valuable.

Full deferred component support in Shorebird would make this
combination — modular on-demand delivery + rapid code patching —
extremely powerful. We understand it is a non-trivial engineering
problem given how Shorebird's patching currently intersects with
Dart's loading unit system, but we would be very glad to see it
supported someday.

Happy to provide more details, logs, or test builds if that would be
useful for your investigation.

[eseidel]

The deferred keyword in Dart is what we've (partially) hijacked in Shorebird internals. One of the reasons why it sees so little usage is that there isn't anything dynamic about it. It only splits out some of the code, not even the constants (iirc). So it's unlikely to save much. It was originally designed for GPay for localization splits, but last I knew they don't even use it. Dart is a whole-program-opimizing compiler (as part of its tree-shaking) so it compiles your whole app, and then just carves off the functions (compiled dart code) for those specific deferred sections into a separate library. I'm not sure how much it will help with a super-app, since those can't be updated independently of the whole.

You're right that if you have sections with 80mb of Dart code it would help. But I'm not aware of an entire Dart program being 80mb, let alone a section of one, so I'd be suspicious you'll get there. I could be wrong (and we do have data I could check, but don't have it easily accessible at the moment).

We don't currently have any plans to support the deferred dart keyword. However we have discussed potentially making improvements (specific to shorebird) for authoring super-apps with Flutter.

Is your intention to author all of the applets with Dart? Will they all ship at the same time with the same release schedule? Are they all written by the same team, or are 3rd parties involved? If there are 3rd parties involved are they providing you their source code for their applets?

[Abdan009]

Thank you for the detailed explanation — this is genuinely clarifying
and reshapes how I think about the problem.

---

An important clarification on the 80MB and size savings

You're right that Dart's deferred keyword only splits compiled Dart
functions into separate loading units. However, I want to clarify that
Flutter's deferred-components system actually combines two separate
mechanisms:

1. Dart loading units — splits compiled Dart code (.so files).
   This is what Shorebird has partially hijacked, and where the
   whole-program compiler limitation applies.

2. Play Feature Delivery asset bundling — assets declared under a
   deferred component in pubspec.yaml are packaged into that feature's
   split APK and only downloaded when the user first accesses the
   feature. This is handled by Play Feature Delivery, independently
   from the Dart loading unit system.

In pubspec.yaml it looks like this:

flutter:
deferred-components:
- name: presence_feature
libraries:
- package:presence/presence.dart
assets:
- assets/presence/svg/ # only downloaded with this feature

We already use this in the current project — SVG icon assets are
bundled inside the presence_feature split APK and are not part of the
base download.

For the super-app, the meaningful size savings we're targeting come
entirely from this asset bundling side — not from Dart code splitting.
The large files are:

• On-device AI model files (.tflite, .onnx) — 20–50MB per model,
  declared as assets under the relevant feature's deferred component
• Native inference libraries (.so files for TFLite, ONNX Runtime,
  etc.) — bundled within the dynamic feature module

These would be declared as assets under each feature's deferred
component, so they are only downloaded when the user first accesses
that specific feature. A user who never uses the face recognition
feature never downloads its 50MB model.

The Dart code portion of each feature is likely only a few MB — so
you're right that the Dart loading unit side contributes little to the
savings. The split APK asset delivery is the real driver here.

Does this change the picture at all from Shorebird's perspective?
The conflict with Shorebird patching is on the Dart loading unit side.
But the asset bundling side is handled by Play Feature Delivery
independently — so in theory, Shorebird could patch the Dart code in
the base loading unit while the feature assets remain in their split
APKs untouched.

---

Answering your questions

Are all applets authored in Dart?
Yes. All features are written in Dart/Flutter by our own internal team.
No cross-platform or web-based mini-program approach.

Same release schedule?
Yes. Everything lives in one monorepo and ships together. There is no
independent release per feature.

Same team or third parties?
Same internal team only. No third parties. We own all source code.

---

What we're most curious about

You mentioned Shorebird has discussed "potentially making improvements
specific to Shorebird for authoring super-apps with Flutter."

We'd genuinely love to understand what direction that might take, even
at a high level. Is the thinking closer to:

• A Shorebird-managed module system where individual features can be
  patched independently?
• A separate Flutter engine instance per applet?
• Or something else entirely?

Our core needs are:

1. On-demand delivery of large feature modules (primarily AI model
   assets, 20–50MB per feature)
2. Fast patching of Dart business logic without a full Play Store
   release cycle

If Shorebird's super-app direction addresses either of these, we would
be very interested — and happy to be an early tester or provide
feedback during design.