> For the complete documentation index, see [llms.txt](https://docs.drizz.dev/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.drizz.dev/reports-and-debugging/troubleshooting.md).

# Troubleshooting

Find the symptom, apply the fix. Three groups: devices, sign-in and network, runs.

|                                  |                                                                                                    |
| -------------------------------- | -------------------------------------------------------------------------------------------------- |
| **Platforms**                    | Android · iOS                                                                                      |
| **Run won't start, vague error** | Check your wallet balance first                                                                    |
| **Run waits without starting**   | No free device, or a lockable pool is fully leased                                                 |
| **Every step slow**              | Cold cache, or caching isn't on for your app                                                       |
| **Watch out**                    | Still stuck after the tables? Use **Report Issue** — it bundles logs, screenshots and device state |

## Prerequisites

Gather these before working through the tables:

* The exact symptom and the screen it appears on
* The run status: `Passed`, `Passed (healed)`, `Failed`, `Error` or `Blocked`
* The device model, OS version and whether it is local, cloud or private
* The desktop app version, and whether the same symptom occurs on another network
* Your wallet balance
* `adb devices` output, for an Android connection problem

## Device won't connect

<table data-search="false"><thead><tr><th>Symptom</th><th>Try</th></tr></thead><tbody><tr><td>Android device not listed</td><td>Run <code>adb devices</code>. If it says <code>unauthorized</code>, accept the prompt on the phone. If it's absent, check the cable</td></tr><tr><td>Emulator listed but won't connect</td><td>adb is stuck or the emulator is still booting — Drizz states which. Wait, or run <code>adb kill-server &#x26;&#x26; adb start-server</code></td></tr><tr><td>Device locked</td><td>Unlock it. Drizz refuses a locked device</td></tr><tr><td>Duplicate emulator launched</td><td>Drizz attaches to a running emulator rather than booting a second. If two appear, close both and reconnect</td></tr><tr><td>iOS simulator won't connect</td><td>Confirm Xcode is installed <em>and has been opened once</em></td></tr><tr><td>iOS "Preparing device" hangs</td><td>Disconnect, re-trust the Mac on the device, reconnect</td></tr><tr><td>WebDriverAgent signature failure</td><td>The Apple team can't sign. Check the team picker — free teams expire weekly</td></tr><tr><td>App won't install on a real iPhone</td><td>The build is a simulator build, or an App Store version of the same bundle ID is installed. Uninstall it first</td></tr></tbody></table>

## Sign-in and network

| Symptom                                      | Try                                                                                          |
| -------------------------------------------- | -------------------------------------------------------------------------------------------- |
| Sign-in completes but the app doesn't log in | Known issue. Quit and relaunch. If it persists, use Report Issue                             |
| Personal email rejected                      | Working as designed. Sign in with your work email                                            |
| Signed in but no apps or files               | Org assignment, or a trial not yet approved. Contact Drizz support. Do not re-install        |
| Files you had before have vanished           | An org-assignment problem, not data loss. Contact Drizz support with your email and org name |
| Works on a hotspot, not on office wifi       | Corporate TLS inspection. Run **Help → Network Preflight**                                   |
| Sign-in hangs on a corporate network         | Corporate TLS inspection. Run Network Preflight first                                        |

## Runs

<table data-search="false"><thead><tr><th>Symptom</th><th>Try</th></tr></thead><tbody><tr><td>Run stuck on "Stopping"</td><td>Drizz recovers this after a timeout. If it doesn't, restart the desktop app</td></tr><tr><td>Run won't start, vague server error</td><td>Check the wallet balance. An exhausted balance does not always present as a billing message</td></tr><tr><td>Run waits without starting</td><td>No free device, or a lockable pool is fully leased — see <a href="/pages/VVqSsKwCSmcNlUyKnWkE">Devices</a></td></tr><tr><td>Runs wait while devices sit idle</td><td>The block is data, not hardware. The lockable pool is smaller than the concurrency setting</td></tr><tr><td>Every step slow</td><td>Cache is cold, or caching isn't enabled for your app — see <a href="/pages/4NRiHtnuovujdAZq5Ptr">Caching</a></td></tr><tr><td>Suite got slower after a release</td><td>Expected. The UI changed and the cache is rebuilding</td></tr><tr><td>Tap fails right after typing</td><td>The keyboard is covering the element — see <a href="/pages/fmEafMB0dQcmof1UPSdo">Type</a></td></tr><tr><td>Screen is black in the report</td><td>Secure screen. The OS blocks capture there, for every tool</td></tr><tr><td>Test plan references a missing app</td><td>The build may have expired — see <a href="/pages/vThWqLQMHIlnE1l3Avr6">Test plans</a></td></tr><tr><td>Run status reads <code>Error</code></td><td>Infrastructure, not your test. Re-run. If it recurs, it's device capacity</td></tr><tr><td>Run status reads <code>Blocked</code></td><td>Billing. Top up the wallet</td></tr><tr><td>Nothing counted as <code>Cancelled</code> any more</td><td>Infrastructure failures now report as <code>Error</code> — see <a href="/pages/75PJpg9l527HNAFO85yu">Statuses</a></td></tr><tr><td>Green run, but a step healed</td><td>The description is weak. Rewrite it — see <a href="/pages/WhpvSc0GZjCheriEDXSF">Self-healing</a></td></tr><tr><td>iOS run much slower than the Android one</td><td>Expected. iOS steps run roughly twice as slow</td></tr><tr><td><code>CLEAR_APP</code> leaves state behind on iOS</td><td>A no-op there. Reset in-app, or use a fresh install</td></tr></tbody></table>

## Still stuck

1. Open the desktop app.
2. Select **Report Issue**.
3. Submit. It bundles your logs, recent screenshots and device state and sends them to Drizz support.

## Next

* [When a step fails](/reports-and-debugging/when-a-step-fails.md)
* [Statuses](/reports-and-debugging/statuses.md)
* [Reading a report](/reports-and-debugging/reading-a-report.md)

***

*Last updated: 6 August 2026*