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.

from modal_computer_use import ActionBatchResult, Screenshot

See the v1.1.0 model source 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.

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:

{
  "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 for module-level transport, validation, budget, artifact, and optional-dependency errors.