Documentation Index
Fetch the complete documentation index at: https://docs.therefrain.ai/llms.txt
Use this file to discover all available pages before exploring further.
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
Recovery hints
Each category includes a localized recovery hint that appears in execution reports and notifications. These hints guide both manual debugging and AI repair suggestions. In self-heal mode, the category is included in the AI prompt to improve repair suggestion accuracy. For example, an “element not found” failure will prompt AI to focus on selector updates, while “page structure changed” will prompt AI to suggest context file updates.What’s next
Self-heal mode
Use error classification to drive AI repair suggestions.
Selector resolution
How elements are found on the page.