ZeptapTroubleshooting
Symptoms, tool error messages and their fixes - blank screen, Bluetooth not connecting, agent can't reach Zeptap, typing and open_app failures.
Find the symptom or the exact error text, then apply the fix. Fixes marked user need a person at the Mac or iPhone; tell the user rather than retrying.
Agent can't reach Zeptap
| Symptom | Fix |
|---|---|
No zeptap tools in the agent | Add Zeptap in Settings › Connectors, then start a new session (or restart the app) of that agent. See Connect an agent |
Connection refused on 127.0.0.1:47801 | Zeptap isn't running. User: open Zeptap. Turn on Open Zeptap at login to avoid this after restarts |
Zeptap isn't running. Open the Zeptap app on this Mac and try again. | The Claude Desktop stdio bridge couldn't start the app within 10 seconds. User: open Zeptap |
| Agent runs on another machine or in a container | The server listens on 127.0.0.1 only. Run the agent on the same Mac |
Screen
| Symptom or message | Fix |
|---|---|
No screen frame available (is the iPhone connected by USB and unlocked?) | Check the USB cable, then unlock the iPhone (unlock, once) |
| Mirror is black while the iPhone is unlocked | User: unplug the USB cable, wait a few seconds, and plug it back in. Or choose Restart Screen from the More menu |
| Can't See Your iPhone | User: unlock the iPhone, then disconnect and reconnect the cable. Tap Trust if the iPhone asks |
| Bluetooth only, plug in USB to see the screen | Touch works but the screen can't be seen. User: connect the USB cable |
Touch and keyboard
| Symptom or message | Fix |
|---|---|
Not connected to the iPhone over Bluetooth. Open Zeptap on the Mac and connect the phone. | User: check Bluetooth is on for both devices and the iPhone is paired with this Mac. Quit other apps that act as a Bluetooth keyboard for the iPhone |
| Bluetooth isn't connecting | User: on the iPhone, open Settings › Bluetooth and tap this Mac. As a last resort, Force Disconnect in Zeptap and pair again |
Couldn't see the pointer. Check AssistiveTouch is on and the iPhone is unlocked. | Zeptap turns AssistiveTouch on over USB; replug the cable to retry. User: or turn it on in Settings › Accessibility › Touch › AssistiveTouch |
| Taps land in the wrong place | Take a fresh screenshot and use its coordinates; after a scroll, re-find the target with find_text |
Tool errors
| Message | Fix |
|---|---|
text "…" not found on screen (0 matches); nothing tapped | The label isn't visible, or OCR reads it differently. Call find_text with a shorter query to see what's on screen, or scroll |
Nothing typed: unsupported characters … | Only US-keyboard ASCII can be typed. Rewrite the text without those characters |
No app named "…" found in Spotlight results; nothing opened. | Use the exact name shown under the app's icon. The app may not be installed |
Tapped "…" but Spotlight still appears open; verify. | Take a screenshot. Call dismiss and try open_app again, or open the app from the Home Screen |
screen still changing after … ms | An animation or video is running. wait, then check again |
unknown tool … or unknown key | Check the name against the tool reference |
Unlock failures are listed in Lock and unlock.
Still stuck
Settings › Preferences › Developer log shows connection status and the raw event log. The debug console exposes the same state from a terminal.
Reddit warmup
21-day Reddit warmup where a brand account earns standing in a few subreddits through helpful comments before posting - stage limits, join, daily-session and post prompts, and Reddit's pushback signals.
Privacy and security
What Zeptap stores, what it sends, who can reach the MCP server, and how the passcode is protected.