nas-tools/iphone_mirroring_troubleshooting.md

# iPhone Mirroring Troubleshooting

## Issue
iPhone Mirroring shows "Unable to Connect to iPhone" error, even though:
- ✅ Same iPhone works on another MacBook
- ✅ iPhone is near the Mac, powered on
- ✅ iPhone is running iOS 18 or later

## Requirements Checklist

### iPhone Requirements
- [ ] iOS 18.0 or later
- [ ] Bluetooth enabled
- [ ] Wi-Fi enabled
- [ ] Signed in to iCloud with same Apple ID as Mac
- [ ] iPhone is unlocked (or recently unlocked)
- [ ] iPhone is near the Mac (within Bluetooth range)

### Mac Requirements
- [ ] macOS Sequoia 15.0 or later
- [ ] Bluetooth enabled
- [ ] Wi-Fi enabled
- [ ] Signed in to iCloud with same Apple ID as iPhone
- [ ] Continuity features enabled

## Common Causes & Solutions

### 1. Different iCloud Account
**Most Common Issue**: Mac and iPhone signed in to different iCloud accounts

**Check:**
```bash
# On Mac - check iCloud account
defaults read MobileMeAccounts Accounts | grep AccountID

# Or check System Settings → Apple ID
```

**Fix:**
- System Settings → Apple ID → Sign in with same account as iPhone
- iPhone: Settings → [Your Name] → Verify Apple ID matches

### 2. Continuity Features Disabled
**Check:**
- System Settings → General → AirDrop & Handoff
- Ensure "Handoff" is enabled
- Ensure "Allow Handoff between this Mac and your iCloud devices" is checked

**Fix:**
```bash
# Enable Handoff via command line
defaults write com.apple.coreservices.useractivityd.plist ActivityAdvertisingAllowed -bool true
defaults write com.apple.coreservices.useractivityd.plist ActivityReceivingAllowed -bool true

# Restart the service
killall sharingd
```

### 3. Bluetooth/Wi-Fi Issues
**Check:**
```bash
# Check Bluetooth status
system_profiler SPBluetoothDataType | grep -A 5 "State"

# Check Wi-Fi status
networksetup -getairportpower en0
```

**Fix:**
- Turn Bluetooth off and on: System Settings → Bluetooth
- Turn Wi-Fi off and on: System Settings → Wi-Fi
- Restart both devices

### 4. macOS Version Too Old
**Check:**
```bash
sw_vers
```

**Fix:**
- iPhone Mirroring requires macOS Sequoia 15.0 or later
- Update macOS: System Settings → General → Software Update

### 5. Firewall Blocking Connection
**Check:**
- System Settings → Network → Firewall
- Check if Firewall is enabled

**Fix:**
- Temporarily disable Firewall to test
- If it works, add exception for "Continuity" or "Handoff"
- Or ensure "Block all incoming connections" is NOT checked

### 6. Network Isolation
**Check:**
- Are Mac and iPhone on the same Wi-Fi network?
- Is there a VPN active on either device?

**Fix:**
- Connect both to same Wi-Fi network
- Disable VPN temporarily to test
- Ensure network allows device-to-device communication (not in guest/isolated mode)

### 7. Bluetooth Permissions
**Check:**
- System Settings → Privacy & Security → Bluetooth
- Ensure apps have Bluetooth access

**Fix:**
- Grant Bluetooth permissions if prompted
- Restart Mac after granting permissions

### 8. Stale Continuity Cache
**Fix:**
```bash
# Reset Continuity/Handoff cache
killall sharingd
killall bluetoothd

# Or restart Bluetooth daemon
sudo launchctl stop com.apple.bluetoothd
sudo launchctl start com.apple.bluetoothd
```

### 9. Reset Network Settings (Last Resort)
**On iPhone:**
- Settings → General → Transfer or Reset iPhone → Reset → Reset Network Settings
- This will reset Wi-Fi passwords but may fix connection issues

**On Mac:**
```bash
# Reset network location (less drastic)
sudo networksetup -setairportpower en0 off
sleep 2
sudo networksetup -setairportpower en0 on
```

## Diagnostic Commands

### Check Continuity Status
```bash
# Check Handoff status
defaults read com.apple.coreservices.useractivityd.plist

# Check Bluetooth connectivity
system_profiler SPBluetoothDataType | grep -i "connected\|paired"
```

### Check System Logs
```bash
# Check for iPhone Mirroring errors
log show --predicate 'eventMessage contains "iPhone Mirroring" or eventMessage contains "Continuity"' --last 1h --info

# Check Bluetooth errors
log show --predicate 'subsystem == "com.apple.bluetooth"' --last 1h --info | tail -50
```

### Check iCloud Account Match
```bash
# Mac iCloud account
defaults read MobileMeAccounts Accounts | grep -A 5 "AccountID"

# Compare with iPhone (check iPhone Settings → [Your Name])
```

### Test Bluetooth Connection
```bash
# List nearby Bluetooth devices
system_profiler SPBluetoothDataType | grep -A 10 "iPhone"
```

## Step-by-Step Troubleshooting

1. **Verify Requirements:**
   - Check macOS version (must be 15.0+)
   - Check iOS version (must be 18.0+)
   - Verify same iCloud account on both devices

2. **Restart Services:**
   ```bash
   killall sharingd
   killall bluetoothd
   ```

3. **Restart Both Devices:**
   - Restart Mac
   - Restart iPhone

4. **Check System Settings:**
   - System Settings → General → AirDrop & Handoff → Enable Handoff
   - System Settings → Privacy & Security → Bluetooth → Ensure enabled
   - System Settings → Network → Firewall → Check settings

5. **Try Again:**
   - Make sure iPhone is unlocked
   - Bring iPhone close to Mac
   - Try connecting again

6. **If Still Not Working:**
   - Sign out and sign back into iCloud on Mac
   - Sign out and sign back into iCloud on iPhone
   - Try again

## Comparison with Working MacBook

Since it works on another MacBook, compare:

1. **macOS Version:**
   ```bash
   sw_vers  # On both Macs
   ```

2. **iCloud Account:**
   - Verify both Macs use same iCloud account
   - Check System Settings → Apple ID

3. **System Settings:**
   - Compare AirDrop & Handoff settings
   - Compare Firewall settings
   - Compare Bluetooth/Wi-Fi settings

4. **Network:**
   - Are both Macs on same network?
   - Any VPN differences?

## Quick Fix Script

```bash
#!/bin/bash
# Quick fix for iPhone Mirroring issues

echo "Resetting Continuity services..."
killall sharingd 2>/dev/null
killall bluetoothd 2>/dev/null

echo "Restarting Bluetooth..."
sudo launchctl stop com.apple.bluetoothd 2>/dev/null
sudo launchctl start com.apple.bluetoothd 2>/dev/null

echo "Checking Handoff settings..."
defaults read com.apple.coreservices.useractivityd.plist ActivityAdvertisingAllowed
defaults read com.apple.coreservices.useractivityd.plist ActivityReceivingAllowed

echo "Done. Please restart your Mac and try again."
```

## Notes

- iPhone Mirroring requires **macOS Sequoia 15.0+** and **iOS 18.0+**
- Both devices must be on same Wi-Fi network (or have Wi-Fi enabled even if using cellular)
- Bluetooth must be enabled on both devices (used for proximity detection)
- Same iCloud account is **required** (not just signed in, but same account)
- Some corporate networks block device-to-device communication
- VPNs can interfere with Continuity features