Troubleshooting

Run the diagnosis

tapscope doctor

Each line is ok, info, warn or fail with a hint. With --json the result is machine-readable for agents. In the app, the states in the sidebar link to the matching guide.

A device is missing

• iPhone or iPad: see iPhone & iPad – trust, unlock, Web Inspector and Wi-Fi pairing.
• Simulator: only booted simulators appear; see iOS Simulator.
• Android: check adb devices -l and the authorization prompt; see Android.
• Whole section missing: it may be switched off in the View menu.

Device listed, but no pages

• Open the page in Safari or Chrome on the device; empty browsers have nothing to inspect.
• iOS: turn on Settings › Apps › Safari › Advanced › Web Inspector.
• Your own app: its WebView must be inspectable, see iOS WebViews or Android WebViews.

The page does not answer

Unlock the device and bring the page to the front. If the notice stays, turn Web Inspector off and on again or reopen the tab. In the CLI this shows up as PAGE_NOT_RESPONDING. More in the iPhone guide.

In the simulator, Safari occasionally stops answering the debugger altogether. Quit it and open the page again:

xcrun simctl terminate booted com.apple.mobilesafari
xcrun simctl openurl booted https://example.com

Port 9222 is busy

If another program already uses port 9222, Tapscope moves to 9223 or the next free port and shows the address at the bottom of the sidebar. tapscope status prints it, and tapscope cdp lists the exact URLs. Point your MCP or Puppeteer configuration to that port, or free 9222 and restart the background service.

Background service

The app and the CLI share one background service. If something seems stuck:

tapscope stop
tapscope status

status starts a fresh service. Its log is in ~/.tapscope/daemon.log. After an update, an older service is replaced automatically.

Free sessions used up

The app shows when the next free session is available, and the CLI returns SUBSCRIPTION_REQUIRED. Listing devices and pages keeps working. See Plans and billing.

Get help

Send the output of tapscope doctor and a short description to support@tapscope.ch.