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

# Troubleshooting

> Common issues and solutions for Agent Browser

## Common Issues

### Browser Launch Failures

#### "Daemon not found" error

This typically occurs when the daemon cannot start or the socket path is unreachable.

**Solutions:**

1. **Clean up stale daemon files:**
   ```bash theme={null}
   # Remove stale socket and PID files
   rm -rf ~/.agent-browser/daemon.sock ~/.agent-browser/daemon.pid
   agent-browser open example.com
   ```

2. **Check socket path length** (common on macOS):
   ```bash theme={null}
   # Socket paths must be < 104 characters on most systems
   # If your home directory path is very long, use a shorter session name
   agent-browser --session short open example.com
   ```

3. **Verify write permissions:**
   ```bash theme={null}
   # Ensure ~/.agent-browser is writable
   ls -la ~/.agent-browser/
   chmod 755 ~/.agent-browser/
   ```

#### Browser fails to launch with custom executablePath

When using a custom Chromium binary (e.g., for serverless deployment), ensure the path is valid and the binary is executable:

```bash theme={null}
# Verify the binary exists and is executable
ls -la /path/to/chromium
chmod +x /path/to/chromium

# Test with explicit path
agent-browser --executable-path /path/to/chromium open example.com
```

See [Serverless Deployment](/guides/serverless) for more on custom browser executables.

### Timeout Errors

#### Default timeout issues

The default Playwright timeout is 25 seconds. This is intentionally below the CLI's 30-second IPC read timeout to ensure proper error messages.

**For slow pages or operations:**

```bash theme={null}
# Increase the default timeout (in milliseconds)
export AGENT_BROWSER_DEFAULT_TIMEOUT=45000
agent-browser open slow-site.com
```

**Note:** Setting timeouts above 30000ms may cause EAGAIN errors because the CLI's read timeout will expire before Playwright responds. The CLI retries automatically, but response times will increase.

**Better approach for slow pages:**

```bash theme={null}
# Use explicit waits instead of relying on default timeout
agent-browser open slow-site.com
agent-browser wait --load networkidle
agent-browser wait "#content"  # Wait for specific element
```

#### IPC EAGAIN errors (os error 35/11)

These errors indicate the daemon is taking too long to respond. Recent versions include automatic retry logic and backpressure-aware socket writes.

**Solutions:**

1. **Update to the latest version:**
   ```bash theme={null}
   npm install -g agent-browser@latest
   ```

2. **Use explicit waits** instead of letting operations time out:
   ```bash theme={null}
   agent-browser wait --load networkidle
   agent-browser wait @e1  # Wait for specific element
   ```

3. **Lower the default timeout** if you're running many operations:
   ```bash theme={null}
   export AGENT_BROWSER_DEFAULT_TIMEOUT=20000
   ```

### Session and State Issues

#### Stale refs after page navigation

Refs (`@e1`, `@e2`, etc.) are invalidated when the page changes. Always re-snapshot after navigation:

```bash theme={null}
agent-browser click @e5  # This might navigate to a new page
agent-browser snapshot -i  # MUST re-snapshot to get fresh refs
agent-browser click @e1  # Use new refs from latest snapshot
```

Ref invalidation happens after:

* Clicking links or buttons that navigate
* Form submissions
* Dynamic content loading (dropdowns, modals)

#### Session conflicts with concurrent agents

Always use named sessions when running multiple automations:

```bash theme={null}
# Each agent gets isolated session
agent-browser --session agent1 open site-a.com
agent-browser --session agent2 open site-b.com

# Check active sessions
agent-browser session list
```

#### State load failures

If state loading fails, ensure:

1. **The browser is running:**
   ```bash theme={null}
   agent-browser open example.com  # Start browser first
   agent-browser state load auth.json  # Then load state
   ```

2. **The state file is valid:**
   ```bash theme={null}
   agent-browser state show auth.json  # Verify state file
   ```

3. **Encryption key matches** (if state is encrypted):
   ```bash theme={null}
   export AGENT_BROWSER_ENCRYPTION_KEY="your-64-char-hex-key"
   agent-browser state load auth.json
   ```

### Network and Certificate Issues

#### HTTPS certificate errors

For development environments with self-signed certificates:

```bash theme={null}
agent-browser --ignore-https-errors open https://localhost:3000
```

**Note:** Only use this for testing. Do not use in production.

#### Proxy SSL inspection issues

Some corporate proxies perform SSL inspection. Combine proxy settings with certificate error ignoring:

```bash theme={null}
agent-browser --proxy http://proxy.corp.com:8080 \
  --ignore-https-errors \
  open https://example.com
```

#### Connection resets and broken pipes

The CLI includes automatic retry logic for transient errors like connection resets, broken pipes, and temporary resource unavailability.

If you still see these errors:

1. **Check network stability**
2. **Restart the daemon:**
   ```bash theme={null}
   agent-browser close
   agent-browser open example.com
   ```

### Platform-Specific Issues

#### Linux: Missing system dependencies

On Linux, Chromium requires system dependencies:

```bash theme={null}
# Install dependencies automatically
agent-browser install --with-deps

# Or manually
npx playwright install-deps chromium
```

#### macOS: Binary permission issues

If postinstall scripts don't run (e.g., when using bun), the native binary may not be executable:

```bash theme={null}
# Make binary executable
chmod +x $(npm root -g)/agent-browser/bin/agent-browser-*
```

#### Windows: CMD wrapper issues

Older versions had issues with the Windows CMD wrapper routing through Node.js. Update to the latest version:

```bash theme={null}
npm install -g agent-browser@latest
```

### JavaScript Evaluation Issues

#### Shell quoting corruption

Complex JavaScript expressions can be corrupted by shell quoting. Use `--stdin` or `-b` to avoid issues:

**Recommended approach with heredoc:**

```bash theme={null}
agent-browser eval --stdin <<'EVALEOF'
JSON.stringify(
  Array.from(document.querySelectorAll("img"))
    .filter(i => !i.alt)
    .map(i => ({ src: i.src.split("/").pop(), width: i.width }))
)
EVALEOF
```

**Alternative with base64 encoding:**

```bash theme={null}
echo 'document.querySelectorAll("div > span").length' | base64 | \
  xargs -I {} agent-browser eval -b {}
```

### Performance Issues

#### Slow command execution with npx

`npx` routes through Node.js before reaching the Rust CLI, adding overhead. For regular use, install globally:

```bash theme={null}
# Install globally for best performance
npm install -g agent-browser
agent-browser install

# Now commands run directly through native binary
agent-browser open example.com
```

#### Large snapshots causing slowdowns

Filter snapshots to reduce output size:

```bash theme={null}
# Interactive elements only
agent-browser snapshot -i

# Compact mode (remove empty structural elements)
agent-browser snapshot -c

# Limit depth
agent-browser snapshot -d 3

# Scope to specific element
agent-browser snapshot -s "#main-content"

# Combine filters
agent-browser snapshot -i -c -d 5 -s "#app"
```

### iOS Simulator Issues

#### Appium connection failures

Ensure Appium and XCUITest driver are installed:

```bash theme={null}
npm install -g appium
appium driver install xcuitest
```

#### Simulator boot timeout

First launch takes 30-60 seconds. Subsequent commands are fast. If boot consistently times out:

1. **Manually boot simulator** and verify it works:
   ```bash theme={null}
   open -a Simulator
   ```

2. **Check available devices:**
   ```bash theme={null}
   agent-browser device list
   ```

#### Real device WebDriverAgent signing issues

For real iOS devices, WebDriverAgent must be code-signed:

1. Open WebDriverAgent project:
   ```bash theme={null}
   cd ~/.appium/node_modules/appium-xcuitest-driver/node_modules/appium-webdriveragent
   open WebDriverAgent.xcodeproj
   ```

2. In Xcode:
   * Select `WebDriverAgentRunner` target
   * Go to Signing & Capabilities
   * Select your Team (free Apple Developer account works)
   * Let Xcode manage signing automatically

## Getting Help

### Enable debug output

```bash theme={null}
agent-browser --debug open example.com
```

### Check browser console for errors

```bash theme={null}
agent-browser console  # View console messages
agent-browser errors   # View uncaught JavaScript exceptions
```

### Report issues

If you encounter a bug, report it at:

**[https://github.com/vercel-labs/agent-browser/issues](https://github.com/vercel-labs/agent-browser/issues)**

Include:

* Agent Browser version: `agent-browser --version`
* Platform and OS version
* Full error message
* Steps to reproduce
* Debug output if available