> 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/when-a-step-fails.md).

# When a step fails

The step that failed is often not the step that is broken. Diagnosis starts at the before-screenshot of the first failing step.

|                        |                                                                              |
| ---------------------- | ---------------------------------------------------------------------------- |
| **Platforms**          | Android · iOS                                                                |
| **Start with**         | The **before**-screenshot of the first failing step                          |
| **Most common cause**  | The description doesn't match the app's exact on-screen wording              |
| **Second most common** | An earlier step didn't do what you thought, so you're on the wrong screen    |
| **Watch out**          | Debug the *first* failing step, not the last. A cascade of red has one cause |

## Prerequisites

Gather these before triaging:

* The report for the failed run
* The **first** failing step in the step list, not the last
* That step's before-screenshot
* The healed-step count for the run
* The device model and OS version the run used

## Why the reported step is not always the broken step

A tap fails because the element is absent. The element is absent because the run is on the wrong screen. The run is on the wrong screen because an earlier step tapped something adjacent, ran before the screen finished loading, or was consumed by a popup. Drizz reports the failure at the point it surfaced, which is the last step in that chain.

The first question is whether the run is on the expected screen. The before-screenshot answers it.

## Triage procedure

1. Open the debug report and locate the **first** failing step.
2. Open that step's **before**-screenshot.
3. Compare it against the screen the step expected.
4. If the screen is wrong, walk back up the step list to the last step whose after-screenshot looked correct. The step immediately after it is the defect. Stop here.
5. If the screen is correct, match the before-screenshot against the symptom table below and apply the fix.
6. Check whether the step carries a healed badge. A healed step has a weak description — rewrite it now — see [Self-healing](/running-tests/self-healing.md).
7. If the step resolved from cache and the UI changed recently, re-run. If it is still wrong on the third run, the description is the cause — see [Caching](/running-tests/caching.md).
8. Re-run the test and confirm the step passes.
9. If it still fails, use **Report Issue** in the desktop app. It bundles logs, screenshots and device state automatically.

## Symptom, cause, fix

<table data-search="false"><thead><tr><th>Symptom in the before-screenshot</th><th>Cause</th><th>Fix</th></tr></thead><tbody><tr><td><strong>Wrong screen entirely</strong></td><td>An earlier step didn't do what you thought</td><td>Fix the earlier step. This step is correct</td></tr><tr><td><strong>Right screen, element off-screen</strong></td><td>Missing scroll</td><td>Add <code>Scroll down until "&#x3C;target>" is visible</code> before the step</td></tr><tr><td><strong>Right screen, element present</strong></td><td>Description doesn't match, or is ambiguous</td><td>Use the app's exact on-screen text; add neighbor or section context</td></tr><tr><td><strong>Screen mid-load, spinner visible</strong></td><td>Missing wait</td><td>Add <code>Wait Until &#x3C;n> Seconds</code> before the step</td></tr><tr><td><strong>Keyboard covering the element</strong></td><td>Keyboard handling</td><td>See <a href="/pages/fmEafMB0dQcmof1UPSdo">Type</a></td></tr><tr><td><strong>Popup covering everything</strong></td><td>Unhandled blocker</td><td>Add a blocker rule in Memory — see <a href="/pages/wl2GqBAWrbDmrlNZGHGT">Memory &#x26; blockers</a></td></tr><tr><td><strong>Black or blank screen</strong></td><td>Secure screen — the OS blocks capture on payment and PIN screens</td><td>Cannot be automated. Restructure the test around it</td></tr><tr><td><strong>Step carries a healed badge</strong></td><td>The description no longer matches the screen</td><td>Rewrite the description — see <a href="/pages/WhpvSc0GZjCheriEDXSF">Self-healing</a></td></tr><tr><td><strong>Cached step acting on a moved element</strong></td><td>Stale resolution after a UI change</td><td>Re-run. If wrong on the third run, fix the description — see <a href="/pages/4NRiHtnuovujdAZq5Ptr">Caching</a></td></tr></tbody></table>

## Fixing a description that doesn't match

Three edits, in order of how often they resolve the failure.

```
# 1 — use the app's exact visible wording, not a paraphrase
Tap on Add to Cart

# 2 — add the element type when the label alone appears twice
Tap on the Add to Cart button

# 3 — anchor to a neighbor or a section when the label repeats in a list
Tap on the plus icon for Running Shoes
Tap on % option under Discount
```

Paraphrasing is the most common cause of a tap landing on the wrong element. If the button reads `Charge Now`, write `Charge Now`.

## Common mistakes

| What you do                                      | What happens                                                        |
| ------------------------------------------------ | ------------------------------------------------------------------- |
| Debug the last red step in a cascade             | You fix a symptom and the run fails one step earlier next time      |
| Re-run and hope                                  | A description failure is deterministic. It fails again              |
| Add a long wait to fix a wrong-element failure   | The suite gets slower and the tap still lands on the wrong element  |
| Handle a global popup with an `IF` in every test | Put it in Memory once — one rule, every test                        |
| Read the after-screenshot to diagnose            | It shows the aftermath. The *before* shows the cause                |
| Report a black screen as a Drizz bug             | Secure screens block capture for every tool. It cannot be automated |

## Next

* [Statuses](/reports-and-debugging/statuses.md)
* [Troubleshooting](/reports-and-debugging/troubleshooting.md)
* [Self-healing](/running-tests/self-healing.md)

***

*Last updated: 6 August 2026*