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

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 — Contains the canonical ErrorStatusEnum and GUIAgentError class definitions
• Legacy compatibility: 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, 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.

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, while an API endpoint example handling GUIAgentError exists in 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:

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 — Defines ErrorStatusEnum, GUIAgentError, and related type definitions
• multimodal/gui-agent/shared/src/types/archived.ts — Legacy copy of error definitions for backward compatibility
• packages/ui-tars/sdk/src/GUIAgent.ts — Implements agent logic and GUIAgentError throwing mechanisms
• apps/ui-tars/src/renderer/src/utils/message.ts — UI layer utilities for displaying error messages
• 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 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.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}