Why this happens
When you try to build and run an app on a physical iPhone or iPad, Xcode may block the launch and show an alert reading <Device Name> is not available. Please reconnect the device. Even more confusingly, the iPhone often still appears in Xcode’s run destination menu while refusing to accept a build.
In most cases, this error is caused by an iOS and Xcode version mismatch. Every release of Xcode ships with support for iOS versions up to a specific point release. If your iPhone updated overnight—even by a minor version—an older Xcode installation cannot mount the Developer Disk Image required to install and debug executables on that OS.
If your Xcode version already supports your iPhone’s iOS version, the error points to a broken device session. A dropped wireless debugging connection, a corrupted pairing record, a locked screen during symbol mounting, or an unconfirmed Developer Mode toggle can all leave Xcode referencing a cached device entry that it can no longer reach.
How to fix it
1. Update Xcode to support your iPhone’s iOS version
Before troubleshooting cables or settings, verify that your Xcode installation supports the exact version of iOS installed on your device.
- On your iPhone, open Settings > General > About and check the iOS Version number.
- On your Mac, check your installed Xcode version and bundled iOS SDKs from Terminal:
xcodebuild -version
xcodebuild -showsdks
Look at the iphoneos SDK version listed in the output. As a general rule, the iOS SDK bundled with Xcode must be equal to or newer than the iOS version running on your test device (for example, debugging on a new minor iOS release typically requires the corresponding Xcode point release).
- If your iPhone runs a public iOS release: Update Xcode through the Mac App Store, or download the latest release archive from the Apple Developer Downloads page.
- If your iPhone runs an iOS beta: A standard App Store build of Xcode will not recognize a newer beta OS. Download and install the matching Xcode beta from Apple Developer Downloads. You can keep Xcode beta alongside your stable
/Applications/Xcode.appwithout overwriting it.
If you keep multiple Xcode versions installed, confirm your active developer directory points to the newer copy:
sudo xcode-select -s /Applications/Xcode.app/Contents/Developer
2. Unpair and re-trust the iPhone in Devices and Simulators
If your Xcode version is already up to date, clearing the cached pairing record forces Xcode to establish a fresh handshake and re-mount developer services on the device.
- In Xcode, open Window > Devices and Simulators (
Shift + Command + 2) and select the Devices tab. - Locate your iPhone in the left sidebar. Look for any yellow warning banner at the top of the detail pane—Xcode often prints a more specific reason there than in the build alert.
- Right-click (or Control-click) your iPhone in the sidebar and click Unpair Device.
- Unplug the USB cable connecting the iPhone to your Mac.
- Return to your project window and run Product > Clean Build Folder (
Shift + Command + K). - Unlock your iPhone so it sits on the Home Screen, then plug it directly into your Mac.
- Tap Trust when the Trust This Computer? prompt appears on the iPhone, and enter your device passcode.
- Wait until the status bar in Devices and Simulators finishes preparing the device before clicking Run.
3. Bypass wireless debugging drops with a direct USB connection
Xcode remembers previously paired devices and attempts to reach them over the local network. If your Mac or iPhone switched Wi-Fi bands, connected to a VPN, or joined a network that blocks Bonjour multicast traffic, Xcode sees the remembered device as offline and throws iPhone is not available. Please reconnect the device.
You can check how Xcode currently sees your iPhone from Terminal using devicectl (available in Xcode 15 and later):
xcrun devicectl list devices
If the state reads unavailable or disconnected:
- Plug the iPhone directly into your Mac using a data-rated Lightning or USB-C cable. Avoid unpowered USB hubs, monitor pass-through ports, and charge-only cables.
- In Window > Devices and Simulators, check whether a network globe icon appears next to your iPhone. In older Xcode versions that expose the Connect via network checkbox, uncheck it temporarily so builds travel strictly over USB.
- Turn off any active VPN or firewall software on either device that filters local network interfaces, as modern Xcode versions establish a local network tunnel even over physical USB.
4. Confirm Developer Mode and reset trust permissions
On iOS 16 and later, Apple requires Developer Mode to be explicitly enabled before Xcode can launch debug builds. Major or minor iOS updates occasionally require you to re-verify this state or re-authorize your Mac.
- On your iPhone, go to Settings > Privacy & Security > Developer Mode.
- Ensure the Developer Mode toggle is green. If it is off, turn it on, tap Restart, and confirm the prompt on screen after the phone boots back up.
- If Xcode still reports the device as unavailable and never triggers the Trust This Computer? dialog after unpairing, unplug the iPhone and go to Settings > General > Transfer or Reset iPhone > Reset > Reset Location & Privacy.
- Enter your passcode to confirm. This clears all trusted computers (alongside per-app location and privacy prompts) and guarantees a fresh trust handshake the next time you connect the cable.
- Restart both Xcode and the iPhone, unlock the phone, reconnect via USB, and approve the trust prompt.
5. A note on copying DeviceSupport folders
If you maintain legacy projects on Xcode 14 or earlier, you can sometimes work around an SDK mismatch without upgrading Xcode by copying the missing iOS version folder into /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport/ from a newer Xcode bundle and restarting Xcode.
However, starting with Xcode 15 and iOS 17, Apple replaced the static DeviceSupport directory workflow with the CoreDevice stack and personalized Developer Disk Images. Copying old DeviceSupport folders no longer works for modern iOS releases—updating Xcode is the only reliable fix.
How to prevent it
- Turn off automatic iOS updates on test hardware: Go to Settings > General > Software Update > Automatic Updates on dedicated test iPhones and disable Install iOS Updates so devices do not outpace your team’s pinned Xcode version overnight.
- Check macOS compatibility before updating iOS: New Xcode releases frequently raise the minimum macOS requirement. Before updating your primary test iPhone to a new major iOS version, verify your Mac can run the required version of Xcode.
- Keep the device unlocked right after iOS updates: The first time you connect an updated iPhone to Xcode, keep the screen awake while Xcode mounts the new Developer Disk Image and copies debug symbols.
- Use direct ports for initial pairing: Always complete the initial pairing and symbol-preparation step over a direct USB cable before relying on wireless debugging.
FAQ
Why does Xcode show my iPhone in the run menu if it is not available?
Xcode caches previously paired devices so they remain selectable for wireless debugging and build configuration checks even when unplugged. If the device appears under an Unavailable heading or fails on launch, Xcode remembers the pairing record but cannot establish an active debug session or lacks SDK support for its current OS.
Do I need to install Xcode beta if my iPhone is on an iOS beta?
Yes. Release versions of Xcode only include Developer Disk Image support up to the public iOS SDKs available when that Xcode build shipped. To build and debug directly on an iPhone running an iOS beta, download the matching Xcode beta from the Apple Developer portal.
How do I force the “Trust This Computer?” alert to appear again?
First try choosing Unpair Device in Xcode under Window > Devices and Simulators and reconnecting the USB cable. If the prompt still does not show on your iPhone, open Settings > General > Transfer or Reset iPhone > Reset > Reset Location & Privacy on the device and plug it back into your Mac.
Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.
