> ## Documentation Index
> Fetch the complete documentation index at: https://mintlify.com/ericclemmons/agent-native/llms.txt
> Use this file to discover all available pages before exploring further.

# Troubleshooting

> Common errors, solutions, and debugging techniques for agent-native

## Common errors

### Accessibility permission denied

**Error message:**

```text theme={null}
Accessibility access denied. Enable in System Settings > Privacy & Security > Accessibility
```

**Cause:** Your terminal or IDE doesn't have Accessibility permissions.

**Solution:**

<Steps>
  <Step title="Open System Settings">
    ```bash theme={null}
    open "x-apple.systempreferences:com.apple.preference.security?Privacy_Accessibility"
    ```

    Or manually: **System Settings > Privacy & Security > Accessibility**
  </Step>

  <Step title="Add your terminal">
    Click the **+** button and add:

    * Terminal.app
    * iTerm.app
    * VS Code
    * Your IDE

    <Tip>If the app is already in the list, try toggling it off and on.</Tip>
  </Step>

  <Step title="Restart your terminal">
    Quit and relaunch your terminal completely for permissions to take effect.
  </Step>

  <Step title="Test access">
    ```bash theme={null}
    agent-native apps
    ```

    If this works, permissions are correctly set.
  </Step>
</Steps>

See AXEngine.swift:378-386 for the access check implementation.

<Warning>
  Changes to Accessibility permissions require a **full restart** of the app. Closing a window is not enough.
</Warning>

### App not found

**Error message:**

```text theme={null}
App not found: Slak
```

**Cause:** Typo in app name, or app is not running.

**Solutions:**

<Accordion title="Check running apps">
  ```bash theme={null}
  agent-native apps
  ```

  This lists all running GUI applications. Verify the exact name.
</Accordion>

<Accordion title="Launch the app first">
  agent-native's `open` command launches apps if they're not running:

  ```bash theme={null}
  agent-native open Slack  # Launches if needed
  ```
</Accordion>

<Accordion title="Use bundle ID">
  If the app name is ambiguous, use the bundle ID:

  ```bash theme={null}
  agent-native open com.tinyspeck.slackmacgap
  ```

  Find bundle IDs with:

  ```bash theme={null}
  agent-native apps --format json | jq '.[] | {name, bundleId}'
  ```
</Accordion>

<Accordion title="Check case sensitivity">
  App names are case-insensitive, but try exact capitalization:

  ```bash theme={null}
  agent-native open "System Settings"  # Correct
  agent-native open "system settings"  # Also works
  ```
</Accordion>

See AXEngine.swift:56-63 for app finding logic.

### Ref not resolving

**Error message:**

```text theme={null}
Ref @n42 not found. It may be stale. Re-snapshot to get fresh refs.
```

**Cause:** The UI structure changed since the last snapshot, invalidating the ref.

**Why this happens:**

* You clicked a navigation element (changed pane/view)
* App loaded new content
* A modal opened or closed
* Window was resized

**Solution:**

```bash theme={null}
# Re-snapshot to get new refs
agent-native snapshot "System Settings" -i

# Now use the new refs
agent-native click @n5
```

<Warning>
  **Always re-snapshot** after actions that change the UI structure.
</Warning>

**Best practice:**

```bash theme={null}
# Take snapshot
agent-native snapshot App -i > /tmp/snap1.txt

# Interact with refs from snap1.txt
agent-native click @n5

# Re-snapshot after UI change
agent-native snapshot App -i > /tmp/snap2.txt

# Use refs from snap2.txt for next interactions
agent-native click @n10
```

See RefStore.swift for ref storage implementation.

### Element not found

**Error message:**

```text theme={null}
Element not found: AXButton[@title="Submit"]
```

**Cause:** The element doesn't exist, or is hidden/disabled.

**Debugging steps:**

<Steps>
  <Step title="Check if element exists">
    ```bash theme={null}
    # Full snapshot (no filters)
    agent-native snapshot App > full-tree.txt

    # Search for your element
    grep -i "submit" full-tree.txt
    ```
  </Step>

  <Step title="Check interactive-only flag">
    The `-i` flag filters to interactive elements. Try without it:

    ```bash theme={null}
    agent-native snapshot App  # Full tree
    ```
  </Step>

  <Step title="Increase depth">
    Default depth is 8. Some deep elements need more:

    ```bash theme={null}
    agent-native snapshot App -i -d 15
    ```
  </Step>

  <Step title="Wait for element to appear">
    Elements may load asynchronously:

    ```bash theme={null}
    agent-native wait App --title "Submit" --timeout 5
    ```
  </Step>

  <Step title="Use find command">
    ```bash theme={null}
    # Search by title
    agent-native find App --title "Submit"

    # Search by role
    agent-native find App --role AXButton

    # Combine filters
    agent-native find App --title "Submit" --role AXButton
    ```
  </Step>
</Steps>

See FindCommand.swift and AXEngine.swift:278-356 for element finding logic.

### Element not responding

**Error message:**

```text theme={null}
Action 'AXPress' failed on: /AXWindow/AXButton
```

**Cause:** Element is disabled, hidden, or doesn't support the action.

**Solutions:**

<Accordion title="Check if element is enabled">
  ```bash theme={null}
  agent-native is enabled @n10
  ```

  If this returns `false`, the element can't be interacted with.
</Accordion>

<Accordion title="Inspect element attributes">
  ```bash theme={null}
  agent-native inspect @n10
  ```

  Check:

  * `AXEnabled`: Should be `true`
  * `Actions`: Should include `AXPress` or relevant action
  * `AXPosition`: Element should be on-screen
</Accordion>

<Accordion title="Try alternative action">
  ```bash theme={null}
  # Instead of click
  agent-native action @n10 AXPress

  # Or focus then press space
  agent-native focus @n10
  agent-native key App space
  ```
</Accordion>

<Accordion title="Wait for element to be ready">
  ```bash theme={null}
  # Wait 1 second
  sleep 1
  agent-native click @n10
  ```
</Accordion>

See InspectCommand.swift for element inspection.

### Timeout waiting for element

**Error message:**

```text theme={null}
Timeout: Element with title="Submit" not found after 5s
```

**Cause:** Element never appeared within the timeout period.

**Solutions:**

<Accordion title="Increase timeout">
  ```bash theme={null}
  agent-native wait App --title "Submit" --timeout 10
  ```
</Accordion>

<Accordion title="Check if element exists">
  Take a snapshot to see what's actually there:

  ```bash theme={null}
  agent-native snapshot App -i
  ```
</Accordion>

<Accordion title="Verify filter criteria">
  Your filters might be too specific:

  ```bash theme={null}
  # Try less specific filter
  agent-native wait App --role AXButton --timeout 5
  ```
</Accordion>

<Accordion title="Check page/pane loaded correctly">
  ```bash theme={null}
  # Check window title
  agent-native get title App

  # Take screenshot
  agent-native screenshot App /tmp/debug.png
  ```
</Accordion>

See WaitCommand.swift for wait implementation.

## Debugging techniques

### Capture full snapshots

When debugging, capture the full tree without filters:

```bash theme={null}
# Save to file
agent-native snapshot App > /tmp/full-tree.txt

# Search for your element
grep -i "keyword" /tmp/full-tree.txt

# View in editor
code /tmp/full-tree.txt
```

### Use JSON output for parsing

```bash theme={null}
# Get JSON snapshot
agent-native snapshot App -i --json > snapshot.json

# Query with jq
cat snapshot.json | jq '.[] | select(.title == "Submit")'

# Extract specific ref
REF=$(cat snapshot.json | jq -r '.[] | select(.title == "Submit") | .ref')
agent-native click "@$REF"
```

### Compare snapshots

See how UI changes between actions:

```bash theme={null}
# Before action
agent-native snapshot App -i > /tmp/before.txt

# Perform action
agent-native click @n5
sleep 1

# After action
agent-native snapshot App -i > /tmp/after.txt

# Compare
diff /tmp/before.txt /tmp/after.txt
```

### Use screenshots for visual debugging

```bash theme={null}
# Capture current state
agent-native screenshot App /tmp/state1.png

# Perform actions
agent-native click @n5

# Capture after state
agent-native screenshot App /tmp/state2.png

# Compare visually
open /tmp/state1.png /tmp/state2.png
```

### Inspect element details

```bash theme={null}
# Full element inspection
agent-native inspect @n10

# Or by filter
agent-native inspect App --title "Submit"
```

Output includes:

* Role and subrole
* All attributes (title, label, value, etc.)
* Available actions
* Position and size
* Enabled/focused state

### Test commands incrementally

Build complex workflows step by step:

```bash theme={null}
# Step 1: Open app
agent-native open App
echo "Opened app"
sleep 1

# Step 2: Snapshot
agent-native snapshot App -i > /tmp/snap.txt
echo "Snapshot captured"

# Step 3: Find element
REF=$(grep -i "submit" /tmp/snap.txt | grep -o 'ref=n[0-9]*' | sed 's/ref=//' | head -1)
echo "Found ref: @$REF"

# Step 4: Click
if [[ -n "$REF" ]]; then
  agent-native click "@$REF"
  echo "Clicked"
else
  echo "Element not found"
  exit 1
fi
```

### Enable verbose output

While agent-native doesn't have a verbose flag, you can wrap commands in debug scripts:

```bash theme={null}
#!/usr/bin/env bash
set -x  # Print commands as they execute
set -euo pipefail  # Exit on error

agent-native open App
agent-native snapshot App -i
agent-native click @n5
```

## Performance issues

### Snapshots are slow

**Cause:** Deep trees with many elements take time to traverse.

**Solutions:**

<Accordion title="Limit depth">
  ```bash theme={null}
  agent-native snapshot App -i -d 5
  ```
</Accordion>

<Accordion title="Use compact flag">
  Remove empty structural elements:

  ```bash theme={null}
  agent-native snapshot App -i -c
  ```
</Accordion>

<Accordion title="Use interactive-only flag">
  Always use `-i` to filter to interactive elements:

  ```bash theme={null}
  agent-native snapshot App -i
  ```
</Accordion>

<Accordion title="Use filter-based commands">
  Skip snapshots when you know what you're looking for:

  ```bash theme={null}
  agent-native click App --title "Submit"
  ```
</Accordion>

See SnapshotCommand.swift:26-33 for interactive role filtering.

### App becomes unresponsive

**Cause:** Too many rapid commands can overwhelm the app.

**Solution:**

Add delays between commands:

```bash theme={null}
agent-native click @n5
sleep 0.5
agent-native fill @n10 "text"
sleep 0.3
agent-native click @n15
```

## Platform-specific issues

### macOS version compatibility

**Issue:** Some features require macOS 13+.

**Check version:**

```bash theme={null}
sw_vers -productVersion
```

**Solution:** Upgrade to macOS 13 (Ventura) or higher.

### Accessibility API changes

Apple occasionally changes Accessibility APIs between macOS versions.

**Solution:**

1. Update agent-native to the latest version:
   ```bash theme={null}
   brew upgrade agent-native
   ```
2. Check for known issues on [GitHub](https://github.com/ericclemmons/agent-native/issues)

## Getting help

<CardGroup cols={2}>
  <Card title="Check GitHub Issues" icon="github" href="https://github.com/ericclemmons/agent-native/issues">
    Search for similar problems and solutions
  </Card>

  <Card title="Run tests" icon="flask">
    Verify your installation:

    ```bash theme={null}
    cd /path/to/agent-native
    make test-quick
    ```
  </Card>

  <Card title="Check accessibility" icon="universal-access">
    Use macOS Accessibility Inspector:

    * Open Xcode
    * Xcode > Open Developer Tool > Accessibility Inspector
    * Inspect app elements manually
  </Card>

  <Card title="File a bug" icon="bug">
    Include:

    * agent-native version (`agent-native --version`)
    * macOS version (`sw_vers`)
    * Full error message
    * Minimal reproduction steps
  </Card>
</CardGroup>

## Quick reference

### Essential debugging commands

```bash theme={null}
# List running apps
agent-native apps

# Full tree snapshot
agent-native snapshot App > debug.txt

# Interactive elements only
agent-native snapshot App -i

# JSON output
agent-native snapshot App -i --json

# Find elements
agent-native find App --title "Submit"

# Inspect element
agent-native inspect @n10

# Check element state
agent-native is enabled @n10
agent-native is focused @n10

# Get element attributes
agent-native get text @n10
agent-native get value @n10

# Screenshot
agent-native screenshot App /tmp/debug.png

# Window title
agent-native get title App
```

### Common error patterns

| Error               | Likely Cause                | Quick Fix                                       |
| ------------------- | --------------------------- | ----------------------------------------------- |
| "access denied"     | No Accessibility permission | Add terminal to System Settings > Accessibility |
| "App not found"     | Typo or not running         | Check `agent-native apps`                       |
| "Ref @nX not found" | UI changed                  | Re-snapshot                                     |
| "Element not found" | Wrong filter or not loaded  | Try `snapshot` without `-i`, or increase `-d`   |
| "Action failed"     | Element disabled            | Check `is enabled`, wait longer                 |
| "Timeout"           | Element never appeared      | Increase `--timeout`, verify filter             |

## Next steps

<CardGroup cols={2}>
  <Card title="System Settings guide" icon="gear" href="/guides/system-settings">
    Learn System Settings automation patterns
  </Card>

  <Card title="Electron apps guide" icon="atom" href="/guides/electron-apps">
    Automate Slack, Discord, VS Code
  </Card>

  <Card title="Safari automation" icon="browser" href="/guides/safari-automation">
    Interact with web content
  </Card>

  <Card title="API reference" icon="code" href="/reference/command-list">
    Complete command reference
  </Card>
</CardGroup>