> ## Documentation Index
> Fetch the complete documentation index at: https://docs.appeeky.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Fix phones that do not show up, actions that fail and approvals that do not arrive, with the real error codes and messages.

Start with **`/dashboard/phones`**. The **Connected** section shows whether your Mac is online, which phones it found, and any setup problem it reported.

***

## The dashboard says "Phones is in private beta"

The **Phones** page of the web dashboard is in private beta. Ask the Appeeky team for access. The API, the MCP tools and Appeeky Desktop work without it, but you need the page to approve actions.

***

## My Mac is not listed

The **Connected** section shows **No phones connected**, or `GET /v1/phones` returns an empty `connectors` array.

| Check | What to do |
| - | - |
| Appeeky Desktop is open | Phones are reachable only while the app is running |
| Sharing is on | **Settings → Phones → Share phones with Appeeky**. The badge should say **Connected** |
| You are signed in | With sharing on but no sign-in, the badge shows **Unavailable** with `Sign in to Appeeky Desktop to share phones.` |
| Same account | The API key or MCP connection must belong to the account that is signed in to Appeeky Desktop |
| The badge says **Reconnecting** | The reason is shown under it. Appeeky Desktop retries on its own. If the reason is `The relay rejected the token.`, sign out of Appeeky Desktop and sign in again |
| The badge says **Unavailable** with `Phones are not available on this Mac` | The phone component could not load on this Mac. The rest of the message gives the reason |

***

## My Mac is online but the phone is missing

The Mac shows **No phones on this Mac right now**. Any problem it found is listed under it and on the **Phone** page of Appeeky Desktop.

### Android

* Turn on **Developer options → USB debugging** and reconnect the cable.
* Unlock the phone and tap **Allow** on the USB debugging prompt. Until you allow it, the phone is not listed.
* Make sure `adb` is installed on the Mac. Appeeky Desktop looks in the Android SDK (`~/Library/Android/sdk/platform-tools`, or `ANDROID_HOME` / `ANDROID_SDK_ROOT`) and then on your `PATH`. Without `adb`, Android phones are not found and no problem is reported.

### iPhone

| Message | What to do |
| - | - |
| `iOS: no iPhone found. Connect one with a cable and unlock it.` | Connect the iPhone with a cable and unlock it. Xcode must be installed on the Mac |
| `Not connected. Plug the iPhone in with a cable and unlock it.` | The Mac knows the iPhone but it is not connected now |
| `Not paired. Unlock the iPhone and tap Trust when it asks.` | Unlock the phone and tap **Trust** |
| `Developer Mode is off. Turn it on: Settings > Privacy & Security > Developer Mode.` | Turn on Developer Mode on the iPhone |
| `No Apple Development certificate found. Sign in to Xcode (Settings > Accounts), then Manage Certificates > + > Apple Development.` | Add your Apple ID in Xcode and create the certificate. A free personal team works |
| `iOS: WebDriverAgent could not start.` | See the next section |

### The iPhone helper app does not start

The **Phone** page in Appeeky Desktop shows **Preparing your iPhone** and the current step.

* **First run takes a few minutes** while Xcode builds the helper app. Setup waits up to 8 minutes for it.
* **Trust the developer.** When the message mentions `VPN & Device Management`, open **Settings → General → VPN & Device Management** on the iPhone and trust your developer certificate. Then use the refresh button.
* **`iproxy failed`.** Install the missing tool with `brew install libimobiledevice`.
* **`could not start ... Is Xcode installed?`** Install Xcode on the Mac.

***

## An action fails

Failed actions return status `422`. Policy errors have their own code. Everything else has the code `PHONE_ACTION_FAILED` and a message. Over MCP you see the same message as the tool's error text.

| Code or message | Why | What to do |
| - | - | - |
| `No phones are online.` | No Mac of your account is sharing a phone | See the sections above |
| `Several phones are online, pass a device id: …` | More than one phone and no `device` | Pass one of the listed ids |
| `No device "…". Call devices to see what is online.` | The device id is wrong or its Mac is offline | List phones again and copy the id. The id starts with the Mac's name |
| `Observe the screen before targeting an element by id.` | You used an element number before any observation | Call `observe` first |
| `The screen changed since the last observation. Observe again before targeting elements by id.` | You used a number from before the last action | Use the numbers from the observation the last action returned, or call `observe` |
| `No element 14. The last observation has 9.` | The number is not in the latest observation | Call `observe` and pick again |
| `… does not support the "back" key. Supported: …` | The phone has no such key. iPhones have no `back` or `app_switch` | Use a listed key, or tap the on-screen button |
| `Could not open …. Is it installed? Use list_apps to check.` | Wrong app id, or the app is not installed | Run `list_apps` and copy the id |
| `wda cannot push media.` | Pushing media works on Android only | Put the file in the iPhone's gallery yourself |
| `Could not download …: HTTP 403.` | The Mac could not download the media link, often because the link expired | Get a fresh link and push again |
| `Media is larger than 512 MB.` | The file is too large | Use a smaller file |
| `Typing non-ASCII text on Android needs …` | The text has accents, non-Latin letters or emoji, and the helper keyboard app is not on the phone | Install the app named in the message, or type plain text |
| `The phone's computer disconnected.` | Your Mac went offline during the action | Check the Mac and Appeeky Desktop, then observe again |
| `… did not answer in time.` | The Mac did not finish the action in time | Check that the phone is unlocked and responsive, then try again |
| `RATE_LIMITED` | More than 30 actions in a minute or 600 in an hour on this phone | Wait and try again. Fewer, larger steps help |
| `APPROVAL_DENIED` | You denied the tap, or nobody decided within 10 minutes | Run the action again when you are ready to approve |
| `APPROVAL_UNAVAILABLE` | The approval request could not be created. Nothing was tapped | Try again |

Other statuses:

| Status | Code | What to do |
| - | - | - |
| 400 | `INVALID_REQUEST` | Check the body. `POST /phones/invoke` needs `{ "invocation": { "method": ... } }` with a known method |
| 502 | `PHONES_RELAY_UNREACHABLE`, `PHONES_RELAY_ERROR` | Appeeky's phone service did not answer. Try again, and check **Phones relay** on [status.appeeky.com](https://status.appeeky.com) |
| 503 | `PHONES_UNAVAILABLE` | Phones are not available on this server |

***

## The agent taps the wrong place

* **Use element numbers, not points,** whenever the element is numbered.
* **Points are screenshot pixels.** The screenshot is scaled down so that its longer edge is at most 1,280 pixels. Use the coordinates from the observation, not the phone's native resolution.
* **The screen was still moving.** An action waits for the screen to settle before it takes the new screenshot. On a screen that never stops moving, such as a video feed, call `observe` again before you act.
* **Nothing happens on a locked phone.** Unlock it and keep the screen on.

***

## An approval does not arrive

* **Check the dashboard first.** Requests appear under **Waiting for you** on **`/dashboard/phones`** within a few seconds. The email can take longer or land in spam.
* **The tap may not need approval.** Only taps and long presses on elements with a label like Post, Send, Buy or Delete pause. See [Approvals and safety](https://docs.appeeky.com/docs/phones/approvals-and-safety.md).
* **It expired.** A request is valid for 10 minutes. After that it moves to **Recent decisions** as `expired` and the agent gets `APPROVAL_DENIED`.
* **Approve does nothing or returns an error.** The request was already decided or has expired. The API answers `404` with `NOT_FOUND`.

***

## The phone agent stops early

| Summary or error | Why |
| - | - |
| `Stopped: A human declined: …` | You denied an approval, or it expired |
| `Reached the 30-step limit.` | The task needs more steps. Split it into smaller tasks |
| `No phones are online.` | The Mac is not sharing a phone. From the **Phone** page of Appeeky Desktop, sharing starts on its own for the run |
| `Several phones are online, pass a device id: …` | Pass `device` in the request |
| `The agent could not start (HTTP 401).` in Appeeky Desktop | Sign out of Appeeky Desktop and sign in again |

See [Phone agent](https://docs.appeeky.com/docs/phones/phone-agent.md) for how runs end.

***

## Still stuck

Check [status.appeeky.com](https://status.appeeky.com) for the **Phones relay** component. Your Mac also keeps a log of every action in `~/.agentthumbs/logs/`, one file per day, which shows what ran and when.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.