Reference

Errors

Every surface carries the same error body: { code, message, data, retryable, requestId }. REST sends it with the HTTP status below, RPC as the typed error's code and data, MCP as a tool result with isError: true. data is read leniently, like an output. A client maps a code it does not know to UNKNOWN. Index.

Implicit error sets

A descriptor spells out every code it can return; the reference abbreviates the common sets by letter.

Set	Constant	Codes
U	`UNIVERSAL_ERRORS`	`VALIDATION`, `CONTRACT_UNSUPPORTED`, `UNAUTHENTICATED`, `FORBIDDEN`, `RATE_LIMITED`, `INTERNAL`
S	`SESSION_ERRORS`	U + `NOT_FOUND`, `SESSION_NOT_READY`, `SESSION_ENDED`, `CAPABILITY_UNSUPPORTED`, `DEVICE_LOST`, `DEVICE_DRIVER_FAILED`, `HOST_LOST`
D	`DRIVE_ERRORS`	S + `SESSION_BUSY`
L	`LOCATOR_ERRORS`	D + `LOCATOR_NOT_FOUND`, `LOCATOR_NOT_ACTIONABLE`, `LOCATOR_STRICT_VIOLATION`, `LOCATOR_REF_STALE`, `APP_NOT_RUNNING`, `APP_CRASHED`, `TIMEOUT`
E	`ENVIRONMENT_ERRORS`	`ENVIRONMENT_HOST_UNSUPPORTED`, `ENVIRONMENT_XCODE_MISSING`, `ENVIRONMENT_XCODE_SETUP_INCOMPLETE`, `ENVIRONMENT_IOS_RUNTIME_MISSING`, `ENVIRONMENT_ANDROID_SDK_MISSING`, `ENVIRONMENT_ANDROID_IMAGE_MISSING`, `ENVIRONMENT_ADB_UNAVAILABLE`, `ENVIRONMENT_DRIVER_NOT_INSTALLED`, `ENVIRONMENT_TOOL_MISSING`, `ENVIRONMENT_UNVERIFIED`, `ENVIRONMENT_DEVICE_HUB_ACTIVE`, `ENVIRONMENT_GUI_SESSION_MISSING`, `ENVIRONMENT_PORTS_UNAVAILABLE`, `ENVIRONMENT_RESERVED_RESOURCE`, `ENVIRONMENT_DISK_LOW`, `ENVIRONMENT_PLATFORM_DISABLED`

General

`VALIDATION`

The input is invalid. HTTP 400; not retryable; test outcome failed.

TypeScript

data: { issues: ValidationIssue[] }

`CONTRACT_UNSUPPORTED`

The requested contract version is not served. HTTP 400; not retryable; test outcome errored.

TypeScript

data: { requested: string; supported: string[] }

`UNAUTHENTICATED`

Authentication is required. HTTP 401; not retryable; test outcome errored.

TypeScript

data: {}

`FORBIDDEN`

The caller is not allowed to do this. HTTP 403; not retryable; test outcome errored.

TypeScript

data: {
  reason: 'insufficient-scope' | 'insufficient-role' | 'trust-required' | 'reauth-required' | 'origin' | 'not-the-merger' | …
  requiredScopes?: string[]
}

`NOT_FOUND`

Not found. HTTP 404; not retryable; test outcome failed.

TypeScript

data: {
  kind: 'session' | 'file' | 'recording' | 'chunk' | 'run' | 'pairing' | 'artifact' | 'path' | 'snapshot' | 'code' | …
  id?: string
}

`CONFLICT`

The request conflicts with the current state. HTTP 409; not retryable; test outcome failed.

TypeScript

data: { reason: string; id?: string }

`TIMEOUT`

The wait timed out. HTTP 408; retryable; test outcome failed.

TypeScript

data: { timeoutMs: number; waitingFor: string; log?: string[] }

`RATE_LIMITED`

Too many requests. HTTP 429; retryable; test outcome errored.

TypeScript

data: { retryAfterMs: number }

`INTERNAL`

An internal error occurred. HTTP 500; retryable; test outcome errored.

TypeScript

data: { requestId: string }

`CAPABILITY_UNSUPPORTED`

The device does not support this. HTTP 422; not retryable; test outcome failed.

TypeScript

data: {
  capability: CapabilityPathOut
  value?: string | number | boolean
  platform?: string
  reason: 'platform' | 'engine' | 'driver' | 'host-version' | 'disabled' | …
}

`CAPACITY_UNAVAILABLE`

No capacity is available right now. HTTP 503; retryable; test outcome errored.

TypeScript

data: {
  retryAfterMs: number
  reason: 'busy' | 'host-pressure' | 'no-matching-host' | 'draining' | 'no-build-machine' | …
}

`HOST_LOST`

The host serving the session was lost. HTTP 503; retryable; test outcome errored.

TypeScript

data: { lostAt: string }

Session, device, app and locator

`SESSION_NOT_READY`

The session is not ready yet. HTTP 409; retryable; test outcome errored.

TypeScript

data: { status: SessionStatusOut }

`SESSION_ENDED`

The session has ended. HTTP 410; not retryable; test outcome errored.

TypeScript

data: { status: SessionStatusOut; reason: SessionReasonOut }

`SESSION_BUSY`

The session is held by another principal. HTTP 409; not retryable; test outcome errored.

TypeScript

data: { holderKind: HolderKindOut }

`DEVICE_SPEC_INVALID`

The device spec cannot be satisfied. HTTP 422; not retryable; test outcome failed.

TypeScript

data: { field: string; value: JsonScalar; available?: string[] }

`DEVICE_BOOT_FAILED`

The device failed to start. HTTP 503; retryable; test outcome errored.

TypeScript

data: { stage: 'create' | 'boot' | 'self-test' | …; detail: string }

`DEVICE_LOST`

The device was lost. HTTP 503; not retryable; test outcome errored.

TypeScript

data: {
  cause: 'shutdown-external' | 'device-hub-quit' | 'crashed' | 'deleted-external' | 'unknown' | …
  fix?: string
}

`DEVICE_DRIVER_FAILED`

The device driver failed. HTTP 503; retryable; test outcome errored.

TypeScript

data: {
  stage: 'build' | 'install' | 'start' | 'handshake' | 'identity' | 'heartbeat' | 'request' | …
  detail: string
}

`DEVICE_MEDIA_FAILED`

The media engine failed. HTTP 503; retryable; test outcome errored.

TypeScript

data: { stage: 'start' | 'capture' | 'encode' | …; detail: string }

`DEVICE_INPUT_UNAVAILABLE`

Live input is unavailable. HTTP 503; retryable; test outcome errored.

TypeScript

data: { reason: 'self-test-failed' | 'device-hub-attached' | 'engine-down' | …; fix?: string }

`APP_NOT_INSTALLED`

The app is not installed. HTTP 409; not retryable; test outcome failed.

TypeScript

data: { bundleId: string }

`APP_NOT_RUNNING`

The app is not running. HTTP 409; not retryable; test outcome failed.

TypeScript

data: { bundleId?: string; state: AppStateOut }

`APP_INSTALL_FAILED`

The app could not be installed. HTTP 422; not retryable; test outcome failed (errored when reason is download-failed).

TypeScript

data: {
  reason: 'invalid-bundle' | 'wrong-platform' | 'wrong-arch' | 'missing-scene-manifest' | 'signature' | 'insufficient-storage' | 'checksum-mismatch' | 'download-failed' | 'other' | …
  detail: string
}

`APP_LAUNCH_FAILED`

The app could not be launched. HTTP 422; not retryable; test outcome failed.

TypeScript

data: {
  bundleId: string
  reason: 'not-launchable' | 'activity-not-found' | 'denied' | 'other' | …
  detail: string
}

`APP_CRASHED`

The app crashed. HTTP 422; not retryable; test outcome failed.

TypeScript

data: {
  bundleId: string
  crashId?: CrashId
  during: 'launch' | 'action' | 'idle' | …
  at: string
  summary?: string
  report: 'pending' | 'attached' | 'unavailable' | …
}

`LOCATOR_NOT_FOUND`

No element matched the locator. HTTP 422; not retryable; test outcome failed.

TypeScript

data: { locator: string; timeoutMs: number }

`LOCATOR_NOT_ACTIONABLE`

The element never became actionable. HTTP 422; not retryable; test outcome failed.

TypeScript

data: {
  locator: string
  check: 'visible' | 'enabled' | 'stable' | 'hittable' | 'editable' | …
  timeoutMs: number
  log: string[]
}

`LOCATOR_STRICT_VIOLATION`

The locator matched more than one element. HTTP 422; not retryable; test outcome failed.

TypeScript

data: { locator: string; count: number; matches: A11yNode[] }

`LOCATOR_REF_STALE`

The element ref is stale. HTTP 409; not retryable; test outcome failed.

TypeScript

data: { ref: string; snapshotId?: SnapshotId }

`SECRET_UNAVAILABLE`

A secret placeholder has no value; nothing was typed. HTTP 422; not retryable; test outcome failed.

TypeScript

data: { names: string[]; reason: 'not-provided' | 'not-supported' | … }

`JS_RUNTIME_UNAVAILABLE`

The app's JavaScript runtime is not available. HTTP 409; retryable when reason is no-target or disconnected or dev-server-unreachable; test outcome failed.

TypeScript

data: {
  reason: 'no-dev-server' | 'dev-server-unreachable' | 'not-a-dev-server' | 'no-target' | 'ambiguous' | 'single-debugger' | 'disconnected' | 'replaced' | 'disabled' | …
  bundleId?: string
  devServerUrl?: string
  candidates?: { appId?: string; deviceName?: string; title?: string }[]
  detail?: string
}

Cloud tenancy, quota and placement

`QUOTA_EXCEEDED`

A quota was exceeded. HTTP 429; retryable when kind is period; test outcome errored.

TypeScript

data: {
  scope: 'org' | 'project' | …
  kind: 'concurrency' | 'period' | …
  dimension: string
  limit: number
  used: number
  retryAfterMs?: number
  class?: string
}

`ORG_SUSPENDED`

The organization is suspended. HTTP 403; not retryable; test outcome errored.

TypeScript

data: {}

`PROJECT_SUSPENDED`

The project is suspended. HTTP 403; not retryable; test outcome errored.

TypeScript

data: { projectId: string }

`SERVICE_SUSPENDED`

The service registration is suspended. HTTP 403; not retryable; test outcome errored.

TypeScript

data: {}

`PROJECT_REQUIRED`

Select a project for this call. HTTP 400; not retryable; test outcome failed.

TypeScript

data: {}

`PLACEMENT_MISMATCH`

The host does not serve this placement. no HTTP status; not retryable; never ends a test; host channel only: never reaches an API caller.

TypeScript

data: { epoch: number }

Environment

`ENVIRONMENT_HOST_UNSUPPORTED`

This host cannot run the platform. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; os: string; arch: string; platform: string }

`ENVIRONMENT_XCODE_MISSING`

Xcode is not installed or not selected. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; selectedPath?: string }

`ENVIRONMENT_XCODE_SETUP_INCOMPLETE`

Xcode setup is incomplete. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; step: 'license' | 'first-launch' | 'components' | … }

`ENVIRONMENT_IOS_RUNTIME_MISSING`

The iOS simulator runtime is not installed. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; os: string }

`ENVIRONMENT_ANDROID_SDK_MISSING`

The Android SDK is incomplete. HTTP 503; not retryable; test outcome errored.

TypeScript

data: {
  fix: string
  docsUrl?: string
  component: 'sdk' | 'emulator' | 'platform-tools' | 'cmdline-tools' | …
  searched: string[]
}

`ENVIRONMENT_ANDROID_IMAGE_MISSING`

The Android system image is not installed. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; package: string }

`ENVIRONMENT_ADB_UNAVAILABLE`

The adb server is unavailable. HTTP 503; not retryable; test outcome errored.

TypeScript

data: {
  fix: string
  docsUrl?: string
  address: string
  reason: 'unreachable' | 'version-mismatch' | 'isolation' | …
}

`ENVIRONMENT_DRIVER_NOT_INSTALLED`

A Troupe driver component is not installed. HTTP 503; not retryable; test outcome errored.

TypeScript

data: {
  fix: string
  docsUrl?: string
  platform: string
  component: 'ios-runner' | 'android-driver' | 'simcap' | 'catalyst-host' | …
}

`ENVIRONMENT_TOOL_MISSING`

A required tool is missing. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; tool: string }

`ENVIRONMENT_UNVERIFIED`

This toolchain version is not verified. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; component: string; version: string; verified: string[] }

`ENVIRONMENT_DEVICE_HUB_ACTIVE`

Device Hub or Simulator.app is attached to Troupe's devices. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; app: 'device-hub' | 'simulator' | … }

`ENVIRONMENT_GUI_SESSION_MISSING`

The platform needs a logged-in GUI session. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string }

`ENVIRONMENT_PORTS_UNAVAILABLE`

No free port in Troupe's range. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; range: string }

`ENVIRONMENT_RESERVED_RESOURCE`

A reserved resource was named. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; resource: string }

`ENVIRONMENT_DISK_LOW`

Free disk space is below the budget. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; path: string; freeBytes: number; requiredBytes: number }

`ENVIRONMENT_PLATFORM_DISABLED`

The platform is disabled on this host. HTTP 503; not retryable; test outcome errored.

TypeScript

data: { fix: string; docsUrl?: string; platform: string }