# Troubleshooting

> Symptoms, tool error messages and their fixes - blank screen, Bluetooth not connecting, agent can't reach Zeptap, typing and open_app failures.

Source: https://zeptap.com/docs/reference/troubleshooting



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 [#agent-cant-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](/agents/connect) |
| `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 [#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 [#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 [#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](/agents/tools)                                                                       |

Unlock failures are listed in [Lock and unlock](/features/lock-and-unlock#the-unlock-tool).

## Still stuck [#still-stuck]

**Settings › Preferences › Developer log** shows connection status and the raw event log. The [debug console](/reference/debug-console) exposes the same state from a terminal.