# Error Status Types in UI-TARS: Complete Handling Guide for GUI Agent Failures

> Master UI-TARS error status types with our complete handling guide. Learn to manage GUI agent failures using ErrorStatusEnum and GUIAgentError for robust recovery.

- Repository: [Bytedance Inc./UI-TARS-desktop](https://github.com/bytedance/UI-TARS-desktop)
- Tags: how-to-guide
- Published: 2026-05-10

---

**UI-TARS defines seven specific error status types**—from screenshot retry failures to environment errors—enabling developers to implement precise recovery strategies through the `ErrorStatusEnum` enumeration and `GUIAgentError` class.

The UI-TARS-desktop repository implements a robust error classification system for GUI automation agents. When the agent encounters operational failures—whether capturing screenshots, invoking model APIs, or executing scripts—it raises a `GUIAgentError` populated with a specific code from `ErrorStatusEnum`. This typed approach allows developers to distinguish between transient retryable errors and fatal failures requiring immediate abort.

## The Seven Error Status Types Defined

UI-TARS centralizes error conditions in the `ErrorStatusEnum` type, exported from the core shared library. Each status combines a numeric value with a specific failure scenario:

| Error Status | Numeric Value | Typical Trigger | Suggested Handling |
| --- | --- | --- | --- |
| `SCREENSHOT_RETRY_ERROR` | `-100000` | Screenshot attempt failed (window not ready) | Retry with configurable limit; surface user message if exhausted |
| `INVOKE_RETRY_ERROR` | `-100001` | Remote invocation (model API) returned error | Apply exponential back-off; fallback to safe state if max retries reached |
| `EXECUTE_RETRY_ERROR` | `-100002` | Generated script or command execution failed | Retry execution; log and abort current step if persistent |
| `MODEL_SERVICE_ERROR` | `-100003` | LLM or model service responded with error | Mark operation failed; optionally switch to secondary model |
| `REACH_MAXLOOP_ERROR` | `-100004` | Agent exceeded allowed loop count | Terminate workflow; report loop limit; review task logic before increasing |
| `ENVIRONMENT_ERROR` | `-100005` | Runtime environment problem (missing dependency, permission) | Abort workflow; surface environment issue; guide user to correct setup |
| `UNKNOWN_ERROR` | `-100099` | Uncategorized failure | Treat as fatal; log full stack trace; optionally send telemetry |

These statuses are wrapped in the **`GUIAgentError`** class, which extends the native JavaScript `Error`. Every raised error populates the `status` field with one of the above enum values, enabling programmatic differentiation between recoverable and unrecoverable failures.

## Core Error Definitions in the Codebase

The error type definitions exist in two locations within the UI-TARS-desktop repository to support both modern and legacy implementations:

- **Primary definition**: [`packages/ui-tars/shared/src/types/agent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/shared/src/types/agent.ts) — Contains the canonical `ErrorStatusEnum` and `GUIAgentError` class definitions
- **Legacy compatibility**: [`multimodal/gui-agent/shared/src/types/archived.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/multimodal/gui-agent/shared/src/types/archived.ts) — Maintains backward compatibility for older GUI-Agent package versions

The agent implementation resides in [`packages/ui-tars/sdk/src/GUIAgent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/GUIAgent.ts), which throws `GUIAgentError` instances with appropriate status codes during task execution.

## Implementing Error Handling in Your Application

When invoking the UI-TARS SDK, wrap agent methods in `try … catch` blocks and check for `GUIAgentError` instances. Switch on the `error.status` property to determine whether to retry, fallback, or abort.

```typescript
import { GUIAgent, GUIAgentError, ErrorStatusEnum } from 'ui-tars-sdk';

const agent = new GUIAgent(/* configuration */);

async function performTask() {
  try {
    await agent.run(/* task definition */);
  } catch (err) {
    // Detect UI-TARS specific errors
    if (err instanceof GUIAgentError) {
      switch (err.status) {
        case ErrorStatusEnum.SCREENSHOT_RETRY_ERROR:
        case ErrorStatusEnum.INVOKE_RETRY_ERROR:
        case ErrorStatusEnum.EXECUTE_RETRY_ERROR:
          // Transient errors - retry with limit
          await retryTask();
          break;

        case ErrorStatusEnum.MODEL_SERVICE_ERROR:
          // Model failure - switch to fallback
          await fallbackModel();
          break;

        case ErrorStatusEnum.REACH_MAXLOOP_ERROR:
        case ErrorStatusEnum.ENVIRONMENT_ERROR:
        case ErrorStatusEnum.UNKNOWN_ERROR:
          // Fatal errors - notify user and stop
          notifyUser(err.message);
          break;

        default:
          // Unexpected status - propagate upstream
          throw err;
      }
    } else {
      // Non-UI-TARS error - propagate
      throw err;
    }
  }
}

```

Reference implementations for error display utilities appear in [`apps/ui-tars/src/renderer/src/utils/message.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/renderer/src/utils/message.ts), while an API endpoint example handling `GUIAgentError` exists in [`examples/operator-browserbase/app/api/agent/route.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/examples/operator-browserbase/app/api/agent/route.ts).

## Retry Strategies for Transient Failures

For errors in the `-100000` to `-100002` range, implement a helper function with exponential back-off before escalating to fatal handling:

```typescript
async function retryTask(maxAttempts = 3) {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      await agent.run(/* same task */);
      return; // Success
    } catch (e) {
      if (e instanceof GUIAgentError &&
          (e.status === ErrorStatusEnum.SCREENSHOT_RETRY_ERROR ||
           e.status === ErrorStatusEnum.INVOKE_RETRY_ERROR ||
           e.status === ErrorStatusEnum.EXECUTE_RETRY_ERROR) &&
          attempt < maxAttempts) {
        // Exponential back-off: 200ms, 400ms, 600ms
        await new Promise(r => setTimeout(r, 200 * attempt));
        continue;
      }
      // Unrecoverable - re-throw
      throw e;
    }
  }
}

```

This pattern specifically handles screenshot capture delays, temporary network failures during model invocation, and transient script execution errors.

## Key Source Files Reference

- [`packages/ui-tars/shared/src/types/agent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/shared/src/types/agent.ts) — Defines `ErrorStatusEnum`, `GUIAgentError`, and related type definitions
- [`multimodal/gui-agent/shared/src/types/archived.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/multimodal/gui-agent/shared/src/types/archived.ts) — Legacy copy of error definitions for backward compatibility
- [`packages/ui-tars/sdk/src/GUIAgent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/sdk/src/GUIAgent.ts) — Implements agent logic and `GUIAgentError` throwing mechanisms
- [`apps/ui-tars/src/renderer/src/utils/message.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/apps/ui-tars/src/renderer/src/utils/message.ts) — UI layer utilities for displaying error messages
- [`examples/operator-browserbase/app/api/agent/route.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/examples/operator-browserbase/app/api/agent/route.ts) — Example API endpoint catching `GUIAgentError` for structured responses

## Summary

- UI-TARS provides **seven specific error statuses** via `ErrorStatusEnum` with numeric values ranging from `-100000` to `-100099`
- Errors are wrapped in **`GUIAgentError`** instances containing a `status` field for programmatic handling
- **Transient errors** (`SCREENSHOT_RETRY_ERROR`, `INVOKE_RETRY_ERROR`, `EXECUTE_RETRY_ERROR`) support retry logic with exponential back-off
- **Fatal errors** (`REACH_MAXLOOP_ERROR`, `ENVIRONMENT_ERROR`, `UNKNOWN_ERROR`) require workflow termination and user notification
- Core definitions reside in [`packages/ui-tars/shared/src/types/agent.ts`](https://github.com/bytedance/UI-TARS-desktop/blob/main/packages/ui-tars/shared/src/types/agent.ts) with legacy support in the `multimodal/` directory

## Frequently Asked Questions

### How do I distinguish UI-TARS errors from standard JavaScript errors?

Check for `instanceof GUIAgentError` before accessing error properties. The `GUIAgentError` class extends the native `Error` object and always includes a `status` field populated with an `ErrorStatusEnum` value, whereas generic JavaScript errors lack this typed structure.

### What is the difference between INVOKE_RETRY_ERROR and MODEL_SERVICE_ERROR?

`INVOKE_RETRY_ERROR` (`-100001`) indicates a transient failure during remote API invocation, such as a network timeout or rate limit, which typically resolves with retry logic. `MODEL_SERVICE_ERROR` (`-100003`) signifies the model service returned a valid error response, suggesting a logic or availability issue that may require switching to a fallback model rather than simple retry.

### How should I handle REACH_MAXLOOP_ERROR in production?

When encountering `REACH_MAXLOOP_ERROR` (`-100004`), terminate the workflow immediately and report the loop limit violation to the user. Unlike transient errors, this indicates the agent has exceeded its safety threshold for iterative operations. Review the task logic for infinite loop conditions before considering an increase to the maximum loop configuration.

### Can I customize which errors trigger automatic retries?

Yes. While UI-TARS categorizes `SCREENSHOT_RETRY_ERROR`, `INVOKE_RETRY_ERROR`, and `EXECUTE_RETRY_ERROR` as inherently transient, you can implement custom retry logic for any error status. However, avoid retrying `ENVIRONMENT_ERROR`, `UNKNOWN_ERROR`, or `REACH_MAXLOOP_ERROR` as these represent configuration failures or logic errors that repetition cannot resolve.