fix-macos-mobile-devices

Utilities and notes for recovering macOS iPhone/iPad device detection when USB sees the device but Finder, Xcode, Safari, or devicectl do not behave correctly.

This repository does not include Apple binaries, frameworks, kexts, receipts, or device-support packages. The script creates a local backup from your own Mac and restores only that local backup.

Symptoms

• system_profiler SPUSBDataType sees an iPhone or iPad.
• Finder or Xcode does not show the device, or shows it as unpaired.
• xcrun devicectl list devices says no devices found, or shows stale/offline state.
• macOS repeatedly prompts to install software required to connect to an iOS/iPadOS device.
• Restarting usbmuxd or restoring the MobileDevice stack makes the device appear without replugging.

Quick Fix

Try restarting Apple mobile-device services first. This does not modify files.

sudo ./scripts/macos-mobiledevice-rescue.sh --kick

Then check state:

./scripts/macos-mobiledevice-rescue.sh --check
xcrun devicectl list devices --columns '*'
xcrun xctrace list devices

Pair A Visible Device

If devicectl shows the iPad as available but Xcode says it is unpaired:

xcrun devicectl manage pair --device <identifier-or-udid>

Keep the device unlocked and accept any prompt on the iPhone/iPad.

For Xcode debugging, enable Developer Mode on the device:

Settings > Privacy & Security > Developer Mode

After rebooting the device, reconnect and check:

xcrun devicectl list devices --columns '*'

Create A Local Backup

Create this before accepting macOS's "software required to connect" prompt or before experimenting with device-support updates.

./scripts/macos-mobiledevice-rescue.sh --backup ~/Desktop

The backup directory contains:

• mobiledevice-working-files.tar.gz
• mobiledevice-working-files.tar.gz.sha256
• paths-relative.txt
• manifest.txt
• RESTORE-NOTES.md
• current-file-checksums.sha256

Do not publish the generated backup. It contains Apple system files from your Mac.

Restore A Local Backup

Use restore only after --kick fails and you have a full system backup.

sudo ./scripts/macos-mobiledevice-rescue.sh --restore ~/Desktop/mobiledevice-snapshot-YYYYMMDD-HHMMSS/mobiledevice-working-files.tar.gz

The script creates a pre-restore backup next to the archive before overwriting anything.

What Gets Backed Up

The backup includes the local copies of:

• AppleMobileDevice.kext
• MobileDevice.framework
• usbmuxd launch configuration
• MobileDeviceUpdater launch configuration
• related private frameworks used by MobileDevice
• CoreTypes mobile-device metadata
• MobileDevice/CoreTypes package receipts

It intentionally does not download, bundle, or redistribute Apple's device-support packages.

Notes

system_profiler visibility is not enough for Xcode debugging. A healthy path usually needs:

• USB enumeration
• usbmuxd mux configuration
• CoreDevice visibility
• trust/pairing
• Developer Mode
• DDI services

connected (no DDI) often means the device is paired but Developer Mode is disabled or DDI services are not available yet.