Troubleshooting
Start with the failing step, its run output and a fresh screenshot. Do not retry every failure in the same way.
| Symptom | What to check |
|---|---|
| App opens but a button is missing | Wait for the expected screen, check dialogs, language and selector match count |
| UIHelper unavailable | Correct foreground app, helper enabled, blacklist, app relaunched after an update |
| Stale element/observation | Query again after navigation; do not reuse an old reference |
| Tap returned but nothing changed | Verify the screenshot, overlays and target; a native acknowledgement is not navigation completion |
| OCR finds nothing | Error pair, language, region, current orientation, text confidence and points versus pixels |
| Image search fails | Opaque template, original pixel size, region size and error string |
| MODULE_NOT_FOUND | Import path relative to the importing file, capitalization and packaged dependencies |
| Unsupported Node module or ES module | Use a compatible CommonJS build and supported ApplesauceOS APIs |
| Script never finishes | Unbounded loop, uncleared interval, repeated recovery or missing deadline |
| Shell output looks successful but the step fails | Inspect execResult code, timedOut, error and stderr |
| Public Markdown returns HTTP 403 in a library client | Try curl or a descriptive User-Agent such as ApplesauceOS-Documentation-Reader/1.0; documentation requires no device credentials |
| MCP result is uncertain | Inspect the original run ID and current device state before retrying |
Preserve useful evidence
Log a short step name before acting and the verified outcome afterward. Avoid passwords, tokens and unrelated personal data. Prefer per-run output over the shared log. Screenshot only when useful; continuous full-screen captures and full-tree queries are unnecessary for most waits.
For a suspected crash, compare the report's timestamp and process to the run. A nearby crash is evidence to inspect, not proof that the last action caused it. Keep user-visible errors descriptive: include the expected screen and what was observed.
Know the limits
App updates, translations and custom views can change selectors. Some permission or system screens belong to another process. A blocked/suspended app may not answer native calls. Stop is cooperative and cannot undo completed actions. Test supported scenarios and make unexpected states fail clearly.