@puberty-labs/clits/docs/ERROR_CODES.md

CLiTS (Chrome Logging and Inspection Tool Suite) is a powerful Node.js library for AI-controlled Chrome browser automation, testing, and inspection. Features enhanced CSS selector support (:contains(), XPath), dry-run mode, element discovery tools, and co

# 🚨 CLITS Error Codes & Recovery Strategies

## Overview

This document provides structured error handling for AI assistants using CLITS. All error responses follow a standardized JSON format for easy programmatic parsing and recovery.

## 📋 **Standard Error Response Format**

```json
{
  "success": false,
  "error": {
    "code": "ERROR_CODE",
    "message": "Human-readable error description",
    "category": "AUTOMATION | NETWORK | SYSTEM | AUTH",
    "severity": "ERROR | WARNING | INFO",
    "context": {
      "command": "interact",
      "selector": "[data-testid='button']",
      "page_url": "https://example.com",
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "First recovery step",
      "Alternative approach",
      "Fallback option"
    ],
    "requires_human_intervention": false
  }
}
```

## 🔴 **Critical Error Codes**

### **ELEMENT_NOT_FOUND**
**Category:** AUTOMATION  
**Severity:** ERROR  
**Requires Human:** false

```json
{
  "success": false,
  "error": {
    "code": "ELEMENT_NOT_FOUND",
    "message": "Could not locate element with selector '[data-testid=\"save-button\"]'",
    "category": "AUTOMATION",
    "severity": "ERROR",
    "context": {
      "command": "interact",
      "selector": "[data-testid='save-button']",
      "page_url": "https://app.example.com/form",
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "Wait for page to fully load and retry",
      "Check if element exists with 'inspect --find-clickable'",
      "Take screenshot with 'vision --screenshot' to diagnose",
      "Try alternative selectors: '[aria-label=\"Save\"]' or text-based targeting"
    ],
    "requires_human_intervention": false
  }
}
```

**AI Recovery Commands:**
```bash
# Step 1: Wait and retry
clits wait --timeout 5000
clits interact --click "[data-testid='save-button']"

# Step 2: Visual diagnosis
clits vision --screenshot --filename "element-not-found-debug.png"
clits inspect --find-clickable --json

# Step 3: Try alternative targeting
clits interact --click-text "Save"
clits interact --click "[aria-label='Save']"

# Step 4: Check page state
clits extract --text "body" | grep -i "save\|submit"
```

---

### **AUTH_REQUIRED**
**Category:** AUTH  
**Severity:** ERROR  
**Requires Human:** true

```json
{
  "success": false,
  "error": {
    "code": "AUTH_REQUIRED", 
    "message": "User authentication required to proceed with this action",
    "category": "AUTH",
    "severity": "ERROR",
    "context": {
      "command": "navigate",
      "page_url": "https://app.example.com/dashboard",
      "detected_redirect": "https://app.example.com/login",
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "Request user to log in manually",
      "Wait for user confirmation before proceeding",
      "Check if already logged in on different tab"
    ],
    "requires_human_intervention": true
  }
}
```

**AI Recovery Protocol:**
```bash
# MANDATORY: Stop automation and request human help
echo "❌ AUTHENTICATION REQUIRED"
echo "Please log in to your account manually, then confirm when ready."
echo "Would you like me to take a screenshot of the current state? (Y/N)"

# Wait for user input before proceeding
# DO NOT attempt automated login
```

---

### **CHROME_NOT_CONNECTED**
**Category:** SYSTEM  
**Severity:** ERROR  
**Requires Human:** false

```json
{
  "success": false,
  "error": {
    "code": "CHROME_NOT_CONNECTED",
    "message": "Cannot connect to Chrome debugging port 9222",
    "category": "SYSTEM", 
    "severity": "ERROR",
    "context": {
      "command": "inspect",
      "chrome_port": 9222,
      "connection_attempt": "http://localhost:9222/json/version",
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "Verify Chrome is running with --remote-debugging-port=9222",
      "Check if port 9222 is available and not blocked",
      "Restart Chrome with debugging enabled",
      "Try alternative port if 9222 is occupied"
    ],
    "requires_human_intervention": false
  }
}
```

**AI Recovery Commands:**
```bash
# Step 1: Check Chrome process
curl http://localhost:9222/json/version

# Step 2: Suggest Chrome restart
echo "Chrome debugging not available. Please run:"
echo "macOS: \"/Applications/Google Chrome.app/Contents/MacOS/Google Chrome\" --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug"

# Step 3: Verify connection
sleep 3
curl http://localhost:9222/json/version
```

---

### **PAGE_UNRESPONSIVE**
**Category:** NETWORK  
**Severity:** WARNING  
**Requires Human:** false

```json
{
  "success": false,
  "error": {
    "code": "PAGE_UNRESPONSIVE",
    "message": "Page failed to respond within timeout period",
    "category": "NETWORK",
    "severity": "WARNING", 
    "context": {
      "command": "navigate",
      "target_url": "https://slow-site.example.com",
      "timeout_ms": 30000,
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "Increase timeout and retry navigation",
      "Check network connectivity", 
      "Try refreshing the page",
      "Verify the URL is correct and accessible"
    ],
    "requires_human_intervention": false
  }
}
```

**AI Recovery Commands:**
```bash
# Step 1: Retry with longer timeout
clits navigate --url "https://slow-site.example.com" --timeout 60000

# Step 2: Check current page state
clits vision --screenshot --filename "page-unresponsive.png"
clits extract --console --log-levels error

# Step 3: Force refresh
clits key --key "F5"
clits wait --timeout 30000
```

---

### **TIMEOUT_EXCEEDED**
**Category:** AUTOMATION  
**Severity:** WARNING  
**Requires Human:** false

```json
{
  "success": false,
  "error": {
    "code": "TIMEOUT_EXCEEDED",
    "message": "Operation timed out waiting for element '[data-testid=\"loading-spinner\"]' to disappear",
    "category": "AUTOMATION",
    "severity": "WARNING",
    "context": {
      "command": "wait",
      "wait_type": "element-gone", 
      "selector": "[data-testid='loading-spinner']",
      "timeout_ms": 15000,
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "Take screenshot to check current page state",
      "Increase timeout duration for slow operations",
      "Check if element selector is correct",
      "Proceed with caution - page may still be loading"
    ],
    "requires_human_intervention": false
  }
}
```

**AI Recovery Commands:**
```bash
# Step 1: Visual check
clits vision --screenshot --filename "timeout-state.png"

# Step 2: Check element status
clits inspect --find-by-selector "[data-testid='loading-spinner']"

# Step 3: Try proceeding or wait longer
clits wait --timeout 30000  # Double the timeout
# OR proceed with next action if safe
```

---

### **INVALID_SELECTOR**
**Category:** AUTOMATION  
**Severity:** ERROR  
**Requires Human:** false

```json
{
  "success": false,
  "error": {
    "code": "INVALID_SELECTOR",
    "message": "CSS selector '[data-testid=button' is malformed - missing closing quote",
    "category": "AUTOMATION",
    "severity": "ERROR",
    "context": {
      "command": "interact",
      "invalid_selector": "[data-testid=button",
      "selector_error": "SyntaxError: missing ) after argument list",
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "Fix CSS selector syntax",
      "Use browser dev tools to test selector",
      "Try alternative targeting methods",
      "Use text-based targeting as fallback"
    ],
    "requires_human_intervention": false
  }
}
```

**AI Recovery Commands:**
```bash
# Step 1: Fix selector syntax
clits interact --click "[data-testid='button']"  # Add missing quote

# Step 2: Use alternative targeting
clits interact --click-text "Button Text"
clits interact --click "[aria-label='Button']"

# Step 3: Validate with dev tools
clits key --key "F12"  # Open dev tools to test selector
```

---

### **PERMISSION_DENIED**
**Category:** SYSTEM  
**Severity:** ERROR  
**Requires Human:** true

```json
{
  "success": false,
  "error": {
    "code": "PERMISSION_DENIED",
    "message": "Browser security policy blocks automated interaction with this element",
    "category": "SYSTEM",
    "severity": "ERROR",
    "context": {
      "command": "interact",
      "selector": "input[type='file']",
      "security_restriction": "File upload requires user gesture",
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "Request user to perform file upload manually",
      "Use keyboard navigation as alternative",
      "Check if element can be targeted differently"
    ],
    "requires_human_intervention": true
  }
}
```

**AI Recovery Protocol:**
```bash
# MANDATORY: Request human intervention
echo "❌ BROWSER SECURITY RESTRICTION"
echo "File upload requires manual user interaction."
echo "Please click the file upload button and select your file manually."
echo "Confirm when ready to continue: (Y/N)"
```

## 🟡 **Warning Codes**

### **ELEMENT_OBSCURED**
**Category:** AUTOMATION  
**Severity:** WARNING  
**Requires Human:** false

```json
{
  "success": false,
  "error": {
    "code": "ELEMENT_OBSCURED",
    "message": "Element is present but not clickable - may be covered by another element",
    "category": "AUTOMATION",
    "severity": "WARNING",
    "context": {
      "command": "interact",
      "selector": "[data-testid='submit-button']",
      "obscuring_element": ".modal-overlay",
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "recovery_suggestions": [
      "Close any overlapping modals or popups",
      "Scroll element into view",
      "Wait for animations to complete",
      "Use keyboard navigation instead"
    ],
    "requires_human_intervention": false
  }
}
```

### **SLOW_RESPONSE**
**Category:** NETWORK  
**Severity:** WARNING  
**Requires Human:** false

```json
{
  "success": true,
  "warning": {
    "code": "SLOW_RESPONSE",
    "message": "Page load took longer than expected (15.2 seconds)",
    "category": "NETWORK",
    "severity": "WARNING",
    "context": {
      "command": "navigate",
      "load_time_ms": 15200,
      "expected_max_ms": 10000,
      "timestamp": "2025-06-24T19:10:45.123Z"
    },
    "suggestions": [
      "Consider increasing default timeouts for this site",
      "Check network connectivity",
      "Monitor for performance issues"
    ]
  }
}
```

## 🔧 **AI Error Handling Best Practices**

### **Error Recovery Workflow**
```bash
# 1. Capture error state
clits vision --screenshot --filename "error-$(date +%s).png"

# 2. Gather diagnostic information
clits extract --console --log-levels error --json > error-console.json
clits inspect --find-clickable --json > available-elements.json

# 3. Attempt recovery based on error code
case $error_code in
  "ELEMENT_NOT_FOUND")
    clits wait --timeout 5000
    clits interact --click-text "$fallback_text"
    ;;
  "AUTH_REQUIRED")
    echo "Human intervention required for authentication"
    exit 1
    ;;
  "TIMEOUT_EXCEEDED")
    clits wait --timeout $((timeout * 2))
    ;;
esac

# 4. Verify recovery success
clits vision --screenshot --filename "recovery-$(date +%s).png"
```

### **Proactive Error Prevention**
```bash
# Always use safe interaction patterns
clits wait --element "$selector" --timeout 10000
clits vision --screenshot --filename "before-action.png"
clits interact --click "$selector"
clits wait --timeout 3000
clits vision --screenshot --filename "after-action.png"
```

### **Error Context Extraction**
```bash
# When error occurs, gather full context
error_context() {
  echo "=== CLITS ERROR CONTEXT ==="
  echo "Timestamp: $(date)"
  echo "Current URL: $(clits extract --url)"
  echo "Page Title: $(clits extract --title)"
  echo "Available Elements:"
  clits inspect --find-clickable --json
  echo "Console Errors:"
  clits extract --console --log-levels error --json
  echo "=========================="
}
```

## 🚀 **Using JSON Error Responses**

### **Enable Structured Error Output**
```bash
# Add --json-errors flag to any command (coming in next update)
clits interact --click ".button" --json-errors

# Parse error response in AI workflows
result=$(clits interact --click ".button" --json-errors 2>&1)
if echo "$result" | jq -e '.success == false' > /dev/null; then
  error_code=$(echo "$result" | jq -r '.error.code')
  echo "Error detected: $error_code"
  # Handle based on error code
fi
```

### **Error Code Priority Handling**
```bash
# Handle errors by severity
handle_error() {
  local error_code=$1
  local requires_human=$2
  
  if [ "$requires_human" = "true" ]; then
    echo "❌ Human intervention required for: $error_code"
    return 1
  fi
  
  case $error_code in
    "ELEMENT_NOT_FOUND"|"TIMEOUT_EXCEEDED")
      echo "⚠️  Retrying with recovery strategy..."
      return 0
      ;;
    "CHROME_NOT_CONNECTED"|"INVALID_SELECTOR")
      echo "🔧 System issue - attempting fix..."
      return 0
      ;;
    *)
      echo "❓ Unknown error: $error_code"
      return 1
      ;;
  esac
}
```

---

**💡 AI Integration Tip:** Always check the `requires_human_intervention` field first. If `true`, immediately stop automation and request user assistance. For `false` errors, attempt the suggested recovery strategies in order.