[Bug]: App does not load after transferring to a new iOS device if over the air updates are installed

[achien]

Capacitor Version

💊 Capacitor Doctor 💊

Latest Dependencies:

@capacitor/cli: 8.0.2
@capacitor/core: 8.0.2
@capacitor/android: 8.0.2
@capacitor/ios: 8.0.2

Installed Dependencies:

@capacitor/cli: 7.4.2
@capacitor/core: 7.4.2
@capacitor/ios: 7.4.2
@capacitor/android: 7.4.2

Other API Details

Platforms Affected

• iOS
• Android
• Web

Current Behavior

I reproduced this issue using 2 iPhones.

1. On the first iPhone, install your app with over the air update support.
2. Open the app and install an over the air update.
3. Factory reset the other iPhone. Set up this iPhone by transferring all apps and data from the first one.
4. Open your app. The app immediately closes.

I reproduced this issue with a debug build of the app to get more info. The steps are really similar.

1. On the first iPhone, install a development build of the app.
2. Install an over the air update.
3. Factory reset the other iPhone. During phone setup choose to transfer apps and data from the first phone. Your app isn't installed yet because it's a development build.
4. Enable developer mode on the second iPhone.
5. Install your development build of the app on this iPhone. It should use the settings and data transferred from the first phone. When the app opens, it'll immediately close.

I see the following in the Xcode debug console

⚡️  ERROR: Unable to load /var/mobile/Containers/Data/Application/6AE4ECD1-1214-4E0D-B66A-D668CD4C2EAC/Library/NoCloud/ionic_built_snapshots/release:824ca27
⚡️  This file is the root of your web app and must exist before
⚡️  Capacitor can run. Ensure you've run capacitor copy at least
⚡️  or, if embedding, that this directory exists as a resource directory.

Expected Behavior

The app opens successfully.

Project Reproduction

https://github.com/achien/capacitor-server-url-reproduction, relevant code is in capacitor-welcome.js

Additional Information

I debugged the issue and I have a patch that fixes the issue for me. The root cause is the app is trying to load from a directory that does not exist using the persisted serverBasePath in the key value store. The directory is <library>/NoCloud/ionic_built_snapshots/<update> which is not transferred from one phone to the other.

This issue does not happen on Android because it checks that the server path exists before using it, here. I was able to fix the issue on iOS by doing the same check.

diff --git a/ios/Capacitor/Capacitor/CAPBridgeViewController.swift b/ios/Capacitor/Capacitor/CAPBridgeViewController.swift
index a7285213..bd8fbaa4 100644
--- a/ios/Capacitor/Capacitor/CAPBridgeViewController.swift
+++ b/ios/Capacitor/Capacitor/CAPBridgeViewController.swift
@@ -93,10 +93,14 @@ import Cordova
         if !isNewBinary && !descriptor.cordovaDeployDisabled {
             if let persistedPath = KeyValueStore.standard["serverBasePath", as: String.self], !persistedPath.isEmpty {
                 if let libPath = NSSearchPathForDirectoriesInDomains(.libraryDirectory, .userDomainMask, true).first {
-                    descriptor.appLocation = URL(fileURLWithPath: libPath, isDirectory: true)
+                    let appLocation = URL(fileURLWithPath: libPath, isDirectory: true)
                         .appendingPathComponent("NoCloud")
                         .appendingPathComponent("ionic_built_snapshots")
                         .appendingPathComponent(URL(fileURLWithPath: persistedPath, isDirectory: true).lastPathComponent)
+
+                    if FileManager.default.fileExists(atPath: appLocation.path) {
+                        descriptor.appLocation = appLocation
+                    }
                 }
             }
         }

[achien]

I've created a reproduction here that uses the filesystem to simulate what is happening. Relevant code is in capacitor-welcome.js.

https://github.com/achien/capacitor-server-url-reproduction

[OS-pedrogustavobilro]

Hey @achien, I was able to reproduce this on iOS using your repo, thank you for sharing it.

Did an equivalent version on Android, and there it doesn't seem to crash.

The patch you shared possibly fixes that issue, but we'll look into it further, possible that the solution may require more than just that.

[fabiomartino]

Hi,
I analyzed this issue and would like to suggest an enhancement to the proposed fix.

Root Cause
The bug occurs because CAPBridgeViewController.swift:94-100 reads the persisted serverBasePath from KeyValueStore and uses it without verifying the directory exists.
After device transfer, the path doesn't exist → crash.

Enhanced Fix
The proposed patch works, but I suggest adding two improvements:

1. Warning log - Helps debugging
2. Clear the persisted key - Prevents repeated failed attempts on every app launch

diff --git a/ios/Capacitor/Capacitor/CAPBridgeViewController.swift b/ios/Capacitor/Capacitor/CAPBridgeViewController.swift
index a7285213..d84e456b 100644
--- a/ios/Capacitor/Capacitor/CAPBridgeViewController.swift
+++ b/ios/Capacitor/Capacitor/CAPBridgeViewController.swift
@@ -93,10 +93,19 @@ import Cordova
         if !isNewBinary && !descriptor.cordovaDeployDisabled {
             if let persistedPath = KeyValueStore.standard["serverBasePath", as: String.self], !persistedPath.isEmpty {
                 if let libPath = NSSearchPathForDirectoriesInDomains(.libraryDirectory, .userDomainMask, true).first {
-                    descriptor.appLocation = URL(fileURLWithPath: libPath, isDirectory: true)
+                    let liveUpdatePath = URL(fileURLWithPath: libPath, isDirectory: true)
                         .appendingPathComponent("NoCloud")
                         .appendingPathComponent("ionic_built_snapshots")
                         .appendingPathComponent(URL(fileURLWithPath: persistedPath, isDirectory: true).lastPathComponent)
+                    // Check if path exists (fixes crash after device transfer)
+                    if FileManager.default.fileExists(atPath: liveUpdatePath.path) {
+                        descriptor.appLocation = liveUpdatePath
+                    } else {
+                        // Path doesn't exist (e.g., after data transfer to new device)
+                        // Clear the invalid persisted path and fallback to default bundle
+                        CAPLog.print("⚡️ WARNING: Live Update path does not exist: \(liveUpdatePath.path). Falling back to default bundle.")
+                        KeyValueStore.standard["serverBasePath"] = nil as String?
+                    }
                 }
             }
         }

Why This Fix is Better

• Without clearing the key, the app will retry the invalid path on every launch
• The warning log helps developers debug issues in production
• Maintains parity with Android (which already has this check per the issue)