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.

from modal_computer_use import ComputerStepResult, Screenshot

See the model source and Step models 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:

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.