> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cloudcruise.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Understanding failures

> How the Maintenance Agent diagnoses a failure and classifies it

The Maintenance Agent evaluates more than the raw error message. Depending on the failure, it can use the error screenshot, visible page state, DOM and selector signals, current URL, failing step, recent actions, context from successful runs, and patterns from previous failed runs. It also learns from recovery outcomes and can apply site-specific knowledge about recurring timing, selector, popup, validation, login, and outage behavior.

The resulting category, sub-type, and explanation are available in the [Retrieve Run Results](https://docs.cloudcruise.com/run-api/retrieve-run-results.md) response as `llm_error_category`, `llm_error_sub_type`, and `llm_error_description`. Terminal failures also include them in the [`execution.failed`](https://docs.cloudcruise.com/concepts/webhooks) webhook.

## Error-classification matrix

| Category | Sub-types | Customer meaning |
| - | - | - |
| `SERVICE_UNAVAILABLE` | `APPLICATION_ERROR`, `SERVICE_RETIRED`, `MAINTENANCE_DOWNTIME`, `SILENT_ERROR` | The external application errored, is under maintenance, was retired, or is silently broken |
| `AUTHENTICATION_ERROR` | `INVALID_CREDENTIALS`, `MFA_CODE_REJECTED`, `ACCESS_DENIED`, `TOO_MANY_ATTEMPTS`, `ACCOUNT_LOCKED` | Login, verification, credentials, or account access failed |
| `PAGE_STILL_LOADING` | `IN_PROGRESS`, `PREMATURE_ACTION` | The page had not finished loading, or the action fired before its target was ready |
| `UNEXPECTED_UI_STATE` | `ACTION_REQUIRED`, `DECISION_REQUIRED` | A popup, dialog, overlay, or banner blocked progress — dismissible, or needing a consequential decision |
| `PASSWORD_UPDATE_REQUIRED` | `DISMISSIBLE`, `NON_DISMISSIBLE` | The site presented an optional or mandatory password-change screen |
| `INCORRECT_INPUTS` | `FIELD_VALIDATION_ERROR`, `NO_MATCHING_OPTION`, `MULTIPLE_MATCHING_RESULTS_FOUND` | An input was rejected by validation, had no matching option, or matched several ambiguous results |
| `XPATH_INCORRECT` | — | A selector found no element, multiple elements, or the wrong element |


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.