Skip to main content

​
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: 
    # 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): 
    # 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: 
    # 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: 
# 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 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: 
# 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: 
# 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: 
    npm install -g agent-browser@latest
  2. Use explicit waits instead of letting operations time out: 
    agent-browser wait --load networkidle
agent-browser wait @e1  # Wait for specific element
  3. Lower the default timeout if you’re running many operations: 
    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: 
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: 
# 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: 
    agent-browser open example.com  # Start browser first
agent-browser state load auth.json  # Then load state
  2. The state file is valid: 
    agent-browser state show auth.json  # Verify state file
  3. Encryption key matches (if state is encrypted): 
    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: 
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: 
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: 
    agent-browser close
agent-browser open example.com

​
Platform-Specific Issues

​
Linux: Missing system dependencies

On Linux, Chromium requires system dependencies: 
# 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: 
# 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: 
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: 
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: 
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: 
# 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: 
# 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: 
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: 
    open -a Simulator
  2. Check available devices: 
    agent-browser device list

​
Real device WebDriverAgent signing issues

For real iOS devices, WebDriverAgent must be code-signed:
  1. Open WebDriverAgent project: 
    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

agent-browser --debug open example.com

​
Check browser console for errors

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 Include:
  • Agent Browser version: agent-browser --version
  • Platform and OS version
  • Full error message
  • Steps to reproduce
  • Debug output if available

Build docs developers (and LLMs) love

Get started for freeTalk to us