Troubleshooting
Quick fixes for common xcross setup, device, signing and build problems.
First, always:
xcross flutter doctor # or: xcross compose doctor
xcross <command> -v # full tool outputDevice
No devices connected
Unlock the iPhone, tap Trust, reconnect, rerun xcross tunnel. On Windows, install iTunes + iCloud from Apple (Requirements).
xcross tunnel fails, or "No RSD tunnel yet"
Run it from an Administrator PowerShell or with sudo. Rerun after every reconnect and keep the phone unlocked.
Wi-Fi device won't connect
Same subnet, UDP 5353 open, phone unlocked. See Run over Wi-Fi.
Device runs iOS 16 or older
Not supported. Launching needs iOS 17+.
Toolchain
swift, clang or ld64.lld missing
On Linux, install Swift 6.4+ yourself, then xcross setup, which installs a working ld64.lld. On Windows, xcross setup offers Swift and LLVM through winget, Scoop, Chocolatey or direct. swiftly’s ld64.lld shim is rejected on purpose.
Swift too old, or parse errors inside a system module
Since 2.0, Linux and Windows need a swift.org toolchain 6.4+ (Xcode 27 SDKs use interfaces older compilers reject), and setup, sdk install and the doctors refuse older ones. Install it (swiftly install latest), then rerun xcross sdk install <Xcode.xip> so the SDK matches.
SDK errors after changing Swift
The SDK is tied to one Swift toolchain. Rerun xcross sdk install <Xcode.xip>.
pymobiledevice3 or Python missing
Windows: install Python 3, then xcross setup. Linux: xcross setup installs it via pipx.
Compose: "Missing JDK 21+"
Point JAVA_HOME at a JDK 21+, or set roots.javaHome in Configuration. Then xcross compose setup --check.
Signing
"Developer Services session has expired"
Run xcross auth --apple-id you@example.com again. Until then, apps that already ran online keep signing from the cache. See Working offline.
Offline run refused (no profile, device not in it, expired)
Offline signing needs one earlier online run of that app on that device, an unexpired profile (7 days on free accounts) and no new extension, capability or App Group. Reconnect once and run again.
ADI libraries unavailable
Auto-download covers Windows and Linux on x64 and ARM64. On other architectures, extract the matching Apple Music APK slice yourself and pass --adi-library-dir.
Build
Flutter plugin skipped (CocoaPods only)
Only SwiftPM plugins build. Use a release with ios/<package>/Package.swift.
Windows: "could not build Objective-C module 'UIKit'"
A Clang module cache race in parallel plugin builds. Fixed in 2.0.2, which prebuilds the SDK modules once and retries a lost race. Run xcross update.
Black screen with "Invalid SDK hash" after a Flutter upgrade
On Linux and Windows flutter precache --ios can leave a stale Flutter.framework. Since 2.0 xcross checks the engine revision and fetches matching artifacts into its own cache, with a one-time warning. Update xcross if you still see it.
"shader not found" or missing ink sparkle
Shaders are compiled with the host impellerc since 2.0, and packages/<pkg>/ shader and font paths resolve like flutter build since 2.0.1. Run xcross update.
Signing fails with "unsupported nested code bundle"
Resource-only .bundle directories (for example GoogleCastCoreResources.bundle or SwiftPM resource bundles) are sealed as resources since 2.0.2. Run xcross update.
Release / AOT build rejected
Flutter release needs gen_snapshot, which only runs on macOS. xcross does debug (JIT) only.
Compose rebuilds are slow
The first Kotlin/Native build is slow (a whole-program compile). Later unchanged builds skip konanc. Use xcross compose run --watch.
Stale build output
xcross flutter clean or xcross compose clean clears this project’s xcross caches. xcross sdk clean removes the Darwin SDK.
Still stuck? Open an issue with the -v log, host OS and iOS version.