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:

   # 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