Troubleshooting¶
Start with the failing layer¶
| Visible symptom | First check | Next reference |
|---|---|---|
| No phone in the picker | Cable, unlock state, macOS accessory approval, Finder visibility, Trust | Device not detected |
| Paired but developer command fails | Developer Mode, DDI compatibility, tunnel, service-specific matrix row | Capability Matrix |
| Man Pages appears busy | Cancel the bounded request and retry from the current project environment | Man Pages |
| Stream has no lines | Confirm the correct stream family, prerequisites, app activity, and raw spool state | Live Logs |
| Backup fails | Encryption state, free space, destination freshness, unlock state | Backup |
| Optional adapter fails | Exact executable path/hash, reported version/build, upstream requirements, independent target state | Ecosystem Tools |
Use the built-in diagnostics¶
- Run Retry Scan for one immediate usbmux check.
- Use Reconnect & Retry… for the guided 30-second physical reconnection window.
- Run Capability Matrix and inspect the first non-ready prerequisite.
- Use Check Command Drift when a guided command may no longer match the installed CLI.
- Create a Sanitized Support Bundle, review it locally, and attach it only when appropriate.
The toolkit does not attempt to restart SIP-protected Apple services, delete pairing records, use sudo, or hide a failed prerequisite behind automatic recovery.
For support, use GitHub Discussions. Follow the support policy before sharing any output.