Troubleshooting

USB device not found

Unlock the iPhone or iPad, reconnect the cable, accept “Trust This Computer”, and confirm the device appears in Finder. Charge-only cables cannot carry MiniBridge traffic.

Black or frozen screen

Open System Settings → Privacy & Security → Screen Recording and enable MiniBridge. Quit and reopen the Mac companion after changing permission.

Pointer or keyboard does nothing

Enable MiniBridge under System Settings → Privacy & Security → Accessibility, then reconnect.

Wi-Fi device not found

Both devices must allow Local Network access, use the same local network, and have MiniBridge open. A paired secure connection is required.

No Internet through iPhone

Check that Personal Hotspot is enabled, the carrier plan supports tethering, the iPhone has cellular service, and macOS shows the iPhone USB network service. MiniBridge does not modify routes automatically.

Mac is not using the iPhone network

Open MiniBridge one-cable diagnostics and compare the iPhone USB interface with the default-route row. Open Network Settings to inspect service status. MiniBridge reports the mismatch but never changes service order or routing.

Virtual display unavailable

MiniBridge isolates the private macOS virtual-display adapter and checks compatibility at runtime. If it is unavailable, attach a temporary monitor or compatible HDMI display adapter. MiniBridge can mirror that display but cannot manufacture a headless screen through a public macOS API.

FileVault screen is unreachable

This is a macOS security boundary. Connect a physical display and keyboard to complete pre-boot unlock, then MiniBridge can start after login.