Fix: Failed to Prepare Device for Development with Xcode and iOS

Fix: Failed to Prepare Device for Development with Xcode and iOS

Written by

in

Quick answer: Unplug your iPhone or iPad, restart the device completely, quit Xcode, and reconnect the cable while the screen is unlocked. If the error persists in Devices and Simulators, unpair and re-trust the device, or update Xcode so its supported SDK matches the iOS version installed on your hardware.

Why this happens

When you plug an iPhone, iPad, or Apple Watch into your Mac, Xcode does more than establish a basic USB connection. Before it can install or debug a build, Xcode has to complete a handshake with the device, mount a matching Developer Disk Image (DDI), and synchronize debugging symbols.

If any step in that handshake stalls, Xcode stops the build and displays Failed to prepare device for development alongside Errors were encountered while preparing your device for development. Please check the Devices and Simulators Window. Inside that window, you will also often see Unable to prepare [Device Name] for development.

In practice, this failure comes down to two main causes. Either a background daemon on iOS or macOS is stuck with a stale session—meaning even a supported Xcode and iOS combination fails to mount the developer image—or your iPhone was recently updated to an iOS version (especially a point release or beta) that your installed version of Xcode does not yet recognize.

How to fix it

Before trying complex workarounds, inspect the exact status message in Xcode by opening Window > Devices and Simulators (or pressing Shift + Command + 2) and selecting your connected device in the left sidebar.

1. Restart your iPhone and Mac

Simply unplugging and reconnecting the USB cable does not reset the background services on iOS that mount the Developer Disk Image. Restarting the physical iOS device is the fastest and most reliable fix when Xcode and iOS were working together previously.

  1. Unplug your iPhone or iPad from your Mac.
  2. Quit Xcode completely (Command + Q).
  3. Power off your iPhone or iPad, wait a few seconds, and turn it back on.
  4. Once the device boots up, unlock it with your passcode and keep it on the Home Screen.
  5. Reopen Xcode, open Window > Devices and Simulators (Shift + Command + 2), and plug the device directly into your Mac.

If the preparation bar still hangs or throws the same error, restart your Mac as well. Rebooting macOS resets usbmuxd and the CoreDevice background services responsible for communicating with physical Apple devices.

2. Unpair and re-trust the device in Xcode

If a reboot does not clear the error, the pairing record stored between your Mac and your iPhone may have become corrupted or out of sync.

  1. Keep your iPhone plugged in and open Window > Devices and Simulators (Shift + Command + 2).
  2. Control-click (or right-click) your iPhone in the left column under Connected.
  3. Select Unpair Device from the context menu.
  4. Unplug the USB cable from your iPhone.
  5. Unlock your iPhone so it is on the Home Screen, then plug the cable back in.
  6. When the Trust This Computer? alert appears on your iPhone, tap Trust and enter your device passcode.

Wait a minute while Xcode re-runs the preparation phase and installs the developer components onto the device.

3. Verify Developer Mode and system components

On iOS 16 and later, Apple blocks local build installation and debugging unless Developer Mode is explicitly enabled on the device. Similarly, Xcode sometimes fails to mount device images if its local system components were not installed after an update.

First, verify Developer Mode on your iPhone or iPad:

  1. Open the Settings app on your device.
  2. Go to Privacy & Security and scroll down to Developer Mode.
  3. Ensure the Developer Mode toggle is turned on. If it is off, enable it, let the device restart, and tap Turn On when prompted after unlocking.

Next, make sure Xcode has finished installing all required platform components on your Mac by running its first-launch installer from Terminal:

sudo xcodebuild -runFirstLaunch

Once that command finishes without errors, reopen Xcode and check the Devices and Simulators window again.

4. Update Xcode to match your iOS version

If your iPhone recently updated to a newer iOS release—or an iOS beta—your current version of Xcode may lack support for that OS build.

Check your device’s exact OS version under Settings > General > About > iOS Version, then check your Xcode version under Xcode > About Xcode.

  • For standard iOS releases: Update macOS if required, then update Xcode through the Mac App Store or download the latest release from the Apple Developer Downloads portal.
  • For iOS beta releases: Standard App Store builds of Xcode generally cannot prepare devices running a newer major or minor iOS beta. Download and install the corresponding Xcode beta from your Apple Developer account.

If you are working with modern Xcode versions (Xcode 15 and later) and iOS 17 or newer, Xcode downloads personalized Developer Disk Images on demand. Make sure your Mac has an active internet connection when you connect a newly updated device for the first time so Xcode can fetch the required image.

Working with legacy Xcode and iOS versions (iOS 16 and earlier)

On older environments (Xcode 14 and earlier debugging iOS 16 and earlier), Xcode relies on static DeviceSupport directories bundled inside the app package. You can inspect which versions an older Xcode installation supports by checking this folder in Terminal:

ls /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport

If you must maintain a legacy Xcode installation, developers have historically copied the matching version folder (for example, 15.4) from a newer Xcode installation into /Applications/Xcode.app/Contents/Developer/Platforms/iPhoneOS.platform/DeviceSupport, restarted Xcode, and reconnected the device. Keep in mind this folder mechanism does not apply to iOS 17 and later, which switched to the CoreDevice architecture.

You can also clear corrupted cached symbols on your Mac so Xcode extracts them cleanly on the next connection:

rm -rf ~/Library/Developer/Xcode/iOS\ DeviceSupport/*

Quit Xcode before running that command, then relaunch Xcode and reconnect your iPhone.

5. Check cables, USB hubs, and VPN tunnels

Physical connection drops and network filters frequently masquerade as device preparation errors:

  • Connect directly to the Mac: Bypass unpowered USB hubs, monitor pass-through ports, and worn Lightning or USB-C cables. Use a data-capable cable plugged straight into your Mac.
  • Disable VPNs or strict firewall rules temporarily: Modern Xcode versions communicate with iOS devices over a local encrypted network tunnel—even when connected via USB. Third-party VPN clients, endpoint security tools, or packet filters that intercept local IPv6 interfaces can block CoreDevice from completing setup.
  • Turn off Connect via Network temporarily: In Window > Devices and Simulators, uncheck Connect via network (if available on your Xcode version) or turn off Wi-Fi briefly on the iPhone so Xcode is forced to prepare the device strictly over the wired connection.

How to prevent it

  • Turn off automatic iOS updates on test devices: Go to Settings > General > Software Update > Automatic Updates on dedicated test phones and turn off Install iOS Updates so an overnight OS update does not outpace your team’s Xcode version.
  • Keep the screen unlocked during initial setup: Set Settings > Display & Brightness > Auto-Lock to 5 Minutes or Never while Xcode prepares a freshly updated device for the first time.
  • Run xcodebuild -runFirstLaunch after every Xcode update: Especially if you install Xcode from .xip archives downloaded from the Apple Developer portal, running this command ensures CoreDevice and mobile device frameworks stay updated.
  • Install Xcode betas alongside release Xcode: Keep a beta Xcode app in /Applications whenever testing pre-release iOS builds so you can prepare beta hardware without breaking your production toolchain.

FAQ

Why did Xcode stop preparing my iPhone even though nothing updated?

Background daemons on iOS that mount the Developer Disk Image can get stuck if the cable was disconnected mid-transfer or if the device went to sleep during symbol setup. Restarting the iPhone clears that state immediately without requiring any software updates.

Does copying files into the DeviceSupport folder still work for recent iOS versions?

No, not for iOS 17 and later. Starting with Xcode 15 and iOS 17, Apple replaced the legacy DeviceSupport folder workflow with CoreDevice and personalized Developer Disk Images, meaning you must update Xcode (and keep your Mac online during initial pairing) to support newer iOS releases.

Where can I see the detailed reason Xcode failed to prepare my device?

Press Shift + Command + 2 in Xcode to open the Devices and Simulators window and click your device in the left sidebar. Look at the yellow or red warning banner at the top of the device pane—clicking the Details button next to the error often reveals the exact underlying failure code or version mismatch.

Sources & credits

Parts of this guide are adapted from content licensed under CC BY-SA 4.0; this article is shared under the same license.