> ## 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.

# Error Classification

> How Refrain automatically categorizes failures for targeted repair.

## 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:

1. If the action was executed but threw an error → **Action failed**
2. If a cached ref was used but the selector couldn't resolve → **Element stale**
3. If the selector failed and the page snapshot changed during retries → **Page structure changed**
4. If the selector failed with no snapshot change → **Element not found**
5. If the error message contains "timeout" or "navigation" → **Navigation timeout**
6. 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

<CardGroup cols={2}>
  <Card title="Self-heal mode" icon="wrench" href="/guides/self-heal">
    Use error classification to drive AI repair suggestions.
  </Card>

  <Card title="Selector resolution" icon="crosshairs" href="/concepts/selector-resolution">
    How elements are found on the page.
  </Card>
</CardGroup>