> ## Documentation Index
> Fetch the complete documentation index at: https://modal-computer-use.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Errors and models

> Review stable result models and recovery errors.

The SDK returns Pydantic models and raises typed exceptions for configuration, lifecycle, placement, transport, and recovery failures.

## Common result models

| Model | Use |
| - | - |
| `ComputerStepResult` | Ordered actions, immediate screenshot, and Step timing |
| `ComputerStepTiming` | Daemon, action, screenshot, and total timing |
| `ActionResult` | One primitive action or command result |
| `ActionBatchResult` | Ordered item results and batch timing |
| `Screenshot` | Image bytes, dimensions, format, digest, capture metadata, and optional cursor position |
| `ScreenshotOptions` | Capture format, cursor, scale, processing, and storage options |
| `ComputerSessionHandle` | Versioned routing identity for placed handoff |
| `SessionRecoveryStatus` | Owner-visible receipt and recovery state |
| `SessionRecoveryAcknowledgement` | Explicit owner recovery result |
| `SandboxCleanupResult` | Cleanup candidates, skips, and errors |
| `ArtifactInfo` and `ArtifactSyncResult` | Artifact metadata and persistence outcome |

Import public models from `modal_computer_use`.

```python theme={"system"}
from modal_computer_use import ComputerStepResult, Screenshot
```

See the [model source](https://github.com/ashtonchew/modal-computer-use/blob/b60c1cb7495200e36a738c0f6e07961b1d2db93c/src/modal_computer_use/models.py) and [Step models](https://github.com/ashtonchew/modal-computer-use/blob/b60c1cb7495200e36a738c0f6e07961b1d2db93c/src/modal_computer_use/steps/models.py) for complete fields.

## Placement and handoff errors

| Error | Meaning |
| - | - |
| `SessionPlacementMissingError` | A required placement value is absent |
| `SessionPlacementMalformedError` | A placement value has an invalid form |
| `SessionPlacementUnverifiableError` | The SDK cannot prove the required placement |
| `SessionPlacementMismatchError` | Function and desktop placement differ |
| `SessionEnvironmentMismatchError` | The Function and desktop use different Modal environments |
| `SessionTargetMismatchError` | The live target does not match the handle |
| `SessionCompatibilityError` | Version or capability checks reject the daemon |
| `SessionBusyError` | Another run owns the lease |
| `SessionLeaseLostError` | The borrower no longer owns the lease |

These checks fail before desktop mutation.

## Mutation and recovery errors

| Error | Meaning |
| - | - |
| `RunSequenceConflictError` | An operation sequence conflicts with session state |
| `ActionOutcomeUnknownError` | The operation may have mutated the desktop |
| `OperationResultUnavailableError` | The operation completed, but its retained result is unavailable |
| `OperationNotAppliedError` | Receipt resolution proves that the operation did not run |
| `SessionRecoveryRequiredError` | The owner must complete explicit recovery |

Never replay an operation after possible dispatch. When a receipt proves completion but the result is unavailable, capture one later frame for diagnosis:

```python theme={"system"}
from modal_computer_use import OperationResultUnavailableError

try:
    step = await computer.step(actions)
except OperationResultUnavailableError as exc:
    frame = await computer.observe_after_result_loss()
    record_sequence(exc.sequence, exc.operation_kind, frame.sha256)
```

The later frame supports diagnosis. Task success and later mutation recovery remain explicit owner
decisions.

## Rate-limit errors

The daemon returns HTTP 429 when the weighted token bucket lacks capacity. `DaemonHTTPError.retry_after_ms` and its allowlisted `Retry-After` header report when capacity should be available. Rate rejection happens before mutation.

## Protect failure data

Errors and logs must not contain bearer tokens, tunnel URLs, clipboard text, typed text, screenshots, artifact bytes, or provider credentials.


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