Skip to content
xcross
Documentation menu

Troubleshooting

Checks and fixes for the most common xcross setup, authentication, device and run problems.

Start every investigation with verbose output and a requirements check - most problems below show up clearly in one of the two:

xcross flutter run -v
xcross setup

-v / --verbose is a global flag available on every xcross command. xcross setup re-checks host requirements: on Linux it installs its apt packages, on Windows it only verifies that the tools are on PATH, and on both it installs pymobiledevice3 if needed.

Device not found or not listed

Check: the iPhone is unlocked, connected, and set to trust this computer - xcross reports No devices connected. Connect an iPhone (and tap Trust), then retry. when the listing is empty. If several devices are attached, an interactive terminal shows a numbered picker; without a terminal (CI, piped stdin) xcross errors and asks you to pass --udid.

Fix: reconnect the cable, confirm you tapped “Trust” on the device, and re-run xcross tunnel. On Linux, xcross setup installs usbmuxd, usbutils, and libimobiledevice-utils, which the device-discovery layer depends on.

xcross tunnel fails or hangs

Check: whether the terminal running xcross tunnel has the privileges the tunnel needs. Creating the TUN interface for the encrypted RSD tunnel requires elevation.

Fix: run it from an Administrator PowerShell on Windows, or as root on Linux. Run it again after every device reconnect. If a later xcross flutter run fails with No RSD tunnel ... yet or Cannot reach the tunneld REST API on 127.0.0.1:49151, the tunnel is not up: re-run xcross tunnel and keep the phone unlocked and trusted.

Developer Disk Image (DDI) does not mount

Check: xcross tunnel output for mount errors; DDI mounting happens as part of that command, before the tunnel starts.

Fix: re-run xcross tunnel with -v to see the underlying pymobiledevice3 step that failed, and confirm the device is unlocked and trusted.

Device runs iOS 16 or older

Check: the device’s iOS version in Settings.

Fix: none available - xcross’s launch protocol targets iOS 17+ CoreDevice over the RSD tunnel. Older devices are not supported for launching.

clang, ld64.lld, or swift missing on PATH

Check: run xcross setup; it verifies swift, clang, clang++, llvm-ar, and ld64.lld (plus flutter on Windows) and reports which ones are missing. A ld64.lld that is only swiftly’s shim is rejected, so it can be reported missing even when the name is on PATH.

Fix: on Linux, xcross setup installs clang, lld, and llvm via apt and symlinks /usr/local/bin/ld64.lld to the newest versioned binary if only ld64.lld-<version> exists. Install the Swift toolchain manually and make sure its bin directory is on PATH. On Windows, install the Swift toolchain and LLVM with winget install --id Swift.Toolchain --exact and winget install --id LLVM.LLVM --exact, then re-run xcross setup.

Python or pymobiledevice3 missing

Check: xcross setup output - it installs or verifies pymobiledevice3 as part of both the Windows and Linux paths.

Fix: on Windows, install Python 3 yourself first - xcross setup reports no Python 3 found otherwise - then let it install pymobiledevice3, or run py -m pip install -U pymobiledevice3. On Linux, xcross setup installs python3, python3-pip, and python3-venv via apt before trying pip install -U pymobiledevice3.

ADI libraries unavailable on non-x86_64 hosts

Check: your CPU architecture. Automatic download of libCoreADI.so / libstoreservicescore.so from the Apple Music APK only happens on Windows x64 and Linux x86_64.

Fix: on other architectures, extract the matching APK slice yourself and pass its directory with xcross auth --adi-library-dir <path>.

Authentication or 2FA failures

Check: whether you’re using Apple ID login or an App Store Connect API key. Developer Services session has expired. Run xcross auth again. means the stored session is no longer valid; note that a valid Apple ID session always wins over a saved API key.

Fix: re-run xcross auth --apple-id you@example.com and enter the 2FA code when prompted. If ADI attestation is the suspected cause, see the ADI library check above. xcross auth never stores your password, only the resulting session, so a stale or revoked session just means signing in again.

Plugin skipped with a CocoaPods-only warning

Check: the plugin’s ios/ directory for a Package.swift. xcross only compiles Swift Package Manager iOS plugins.

Fix: switch to a plugin release that includes ios/<package_name>/Package.swift, or drop the plugin if no such release exists yet.

Release or AOT attempts fail

Check: xcross flutter build and xcross flutter run have no release or profile flags at all, so passing one is rejected as a usage error.

Fix: none within xcross - it only targets debug (JIT) runs on a device. Release/AOT output requires Flutter’s macOS tooling, because gen_snapshot for iOS only runs on macOS.

Next steps

Edit on GitHubReport an issue
ESC