Migration fails during live update when upgrading Capacitor plugins

Answer to the Core Question

When you upgrade a Capacitor plugin in an Ionic Angular app that uses Ionic App Flow live updates, the update can fail if the new plugin binary introduces native code changes that the live‑update engine cannot patch incrementally. The live‑update process expects the native project to be in the exact state that the web bundle was built against. If the plugin adds new files, changes existing ones, or requires a newer Capacitor SDK, the incremental patch will abort.

Confirmed Facts

• The failure occurs during the live‑update phase, not during the initial build or npx cap sync.
• Live updates only support incremental changes; any native code modification that changes the bundle’s binary layout forces a full native rebuild.
• Capacitor’s diagnostics can detect mismatches between the web bundle, plugin.xml, and the native project.
• App Flow’s live‑update API does not automatically rebuild native projects; you must perform a full rebuild before pushing an update that includes a new plugin version.

Likely Explanation

Most plugin upgrades add new Android/iOS source files or modify the native manifest. When the web bundle is built with the old plugin, the native project contains the old binaries. A live‑update attempt to replace only the web assets cannot reconcile the binary differences, so the update process aborts.

Steps to Keep Web Bundle & Plugins in Sync

1. Pin plugin versions in package.json and capacitor.config.json and avoid caret (^) or tilde (~) ranges that can pull in breaking changes during a build.

   npm install @capacitor/core@5.0.0 @capacitor/ios@5.0.0 @capacitor/android@5.0.0
   

2. Run diagnostics before building:

   ionic capacitor diagnostics
   

   This checks that the native projects match the web bundle and that all required plugin files are present.
3. Sync and rebuild the native project after any plugin change:

   npx cap sync
   npx cap copy
   npx cap open ios   # or android
   # Build in Xcode/Android Studio and run a local test
   

   If the build succeeds, the plugin binary is now compatible with the native runtime.
4. Test the bundle locally by launching the app on a device or simulator with the freshly built native project. Verify that the app starts and the new plugin functionality works.
5. Package the web bundle (e.g., ionic build) and push the update to App Flow. The live‑update will now only replace the web assets; the native binaries are already up‑to‑date.
6. Use App Flow’s “Rollback” or “Versioning” features to provide a safety net. If the update causes a crash, users can revert to the previous bundle while you deploy a corrected version.

Detecting Version Conflicts Early

• Check the plugin.xml of the updated plugin for android or ios sourceFile entries that differ from the current native project.
• Run npx cap sync and watch the console for warnings such as "missing file" or "duplicate class".
• Compare the Capacitor SDK version in capacitor.config.json with the plugin’s required SDK. If the plugin needs a newer SDK, update Capacitor itself.
• If a plugin upgrade introduces a breaking API change, run a unit test that imports the plugin in a minimal Angular component and verifies the public API.

What to Do If a Conflict Is Detected

1. Revert the plugin to the last working version in package.json and redeploy.
2. Upgrade Capacitor to the version required by the plugin, then repeat the sync‑build‑test cycle.
3. Consider splitting the new plugin’s functionality into a separate feature flag that can be toggled on after the native project is confirmed to build.

Missing Diagnostic Detail

To tailor the recommendation to your specific failure, could you share the exact error message or log snippet that appears during the live‑update step?