Overview
When a step fails during execution, Refrain automatically classifies the failure into one of 6 categories. This classification drives self-healing behavior — each category maps to specific recovery strategies and AI repair suggestions. Error classification is available on all plans and runs automatically during both normal execution and self-heal mode.The 6 categories
| Category | Condition | Recommended action |
|---|---|---|
| Element not found | Selector resolution failed and the page snapshot didn’t change | Update the selector’s ariaLabel, role, or text to match the current UI |
| Element stale | A cached selector ref no longer exists on the page | Clear the selector cache and re-execute |
| Page structure changed | The page snapshot changed between retries (the page is different from when the runbook was generated) | Update context.md with the new page structure |
| Navigation timeout | A timeout or navigation-related error occurred | Add a wait step before the failing step |
| Action failed | The element was found but the action threw an exception | Review the action type — the element may need a different interaction |
| Unknown | None of the above conditions matched | Review the error details manually |
How classification works
Classification is deterministic — it uses the execution context (not AI) to categorize failures:- If the action was executed but threw an error → Action failed
- If a cached ref was used but the selector couldn’t resolve → Element stale
- If the selector failed and the page snapshot changed during retries → Page structure changed
- If the selector failed with no snapshot change → Element not found
- If the error message contains “timeout” or “navigation” → Navigation timeout
- Otherwise → Unknown