> ## 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 v1.1.0 result models and top-level error types.

The SDK returns Pydantic models for structured results. It raises typed exceptions for configuration, lifecycle, and session handoff failures.

## Common result models

| Model | Use |
| - | - |
| `ActionResult` | Result of one primitive action or command |
| `ActionBatchResult` | Ordered results and batch timing |
| `ActionBatchTiming` | Daemon elapsed time for a batch |
| `ActionItemResult` | Result for one batch item |
| `Screenshot` | Image bytes, dimensions, format, and digest |
| `ScreenshotOptions` | Screenshot capture and processing options |
| `Point` and `Region` | Coordinates and rectangular regions |
| `DisplayInfo` and `DisplayGeometry` | Display metadata and coordinate geometry |
| `X11Window` | Window identity, title, bounds, and state |
| `Recording` | Recording state, path, duration, size, and digest |
| `ArtifactInfo` | Artifact path, size, and metadata |
| `ArtifactSyncResult` | Persistence sync outcome |
| `ProcessStatus` | Supervised process state |
| `ComputerStatus` | Desktop lifecycle and budget state |
| `SandboxRef` | Sanitized Sandbox and session metadata |
| `SandboxCleanupResult` | Cleanup candidates, skips, and errors |
| `ComputerSessionHandle` | Versioned routing identity for session handoff |
| `SessionRecoveryStatus` | Owner-visible recovery state |
| `SessionRecoveryAcknowledgement` | Explicit owner recovery result |

Import these models from `modal_computer_use`.

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

See the [v1.1.0 model source](https://github.com/ashtonchew/modal-computer-use/blob/4425402dbc681133252dbc54d971ea4c95bc0ffc/src/modal_computer_use/models.py) for complete fields.

## Top-level error types

The v1.1.0 package exports these errors at `modal_computer_use`:

| Error | Meaning |
| - | - |
| `ConfigConflictError` | An existing Sandbox does not match the requested configuration. |
| `BrowserReadinessError` | The configured browser did not reach the required ready state. |
| `FrameValidationError` | A frame is empty, invalid, or incompatible. |
| `SandboxUnavailableError` | A Sandbox cannot be found or contacted. |
| `SandboxAmbiguousError` | An attach query matches more than one Sandbox. |
| `SessionBorrowError` | Base class for safe session-borrow failures. |
| `SessionCompatibilityError` | The session does not support the requested handoff protocol. |
| `SessionEnvironmentMismatchError` | The runtime environment does not match session policy. |
| `SessionPlacementMismatchError` | Function placement does not match session policy. |
| `SessionTargetMismatchError` | The live target does not match the handle. |
| `SessionBusyError` | Another run owns the session lease. |
| `SessionLeaseLostError` | The borrower no longer owns the lease. |
| `RunSequenceConflictError` | An operation sequence conflicts with session state. |
| `ActionOutcomeUnknownError` | An action may have run, but its outcome is unknown. |
| `OperationResultUnavailableError` | An 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. |

## Do not replay unknown mutations

Treat `ActionOutcomeUnknownError` as an indeterminate mutation. Do not replay the action through another route.

`OperationResultUnavailableError` exposes a nonnegative `sequence` and an allowlisted `operation_kind` when the daemon supplied one. A borrowed client can call `observe_after_result_loss()` to capture one later full-screen PNG. That observation does not prove semantic success. It does not unblock later mutations in the same borrow.

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

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

## Daemon errors

Direct primitive failures use this JSON shape:

```json theme={"system"}
{
  "code": "input_backend_unavailable",
  "message": "Input backend is unavailable",
  "details": {
    "retry_safe": true,
    "emission_state": "not_started"
  }
}
```

Batch item failures use the same stable code as `error_code`. They place structured details in `output`.

`retry_safe` describes duplicate-execution safety. It does not mean that automatic retry will succeed.

See the [v1.1.0 error source](https://github.com/ashtonchew/modal-computer-use/blob/4425402dbc681133252dbc54d971ea4c95bc0ffc/src/modal_computer_use/errors.py) for module-level transport, validation, budget, artifact, and optional-dependency errors.


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