---
title: "Debugging"
description: "Browser automation CLI for AI agents"
canonical_url: "https://agent-browser.dev/debugging"
---

# Debugging

Use debugging commands to inspect browser logs, page errors, JavaScript dialogs, Chrome DevTools traces, highlighted elements, and the live DevTools frontend during automation.

## Console and page errors

```bash
agent-browser console
agent-browser console --json
agent-browser console --clear

agent-browser errors
agent-browser errors --clear
```

<table>
  <thead>
    <tr><th>Command</th><th>Description</th></tr>
  </thead>
  <tbody>
    <tr><td><code>console</code></td><td>Show browser console messages</td></tr>
    <tr><td><code>console --json</code></td><td>Show structured console output with raw CDP arguments</td></tr>
    <tr><td><code>console --clear</code></td><td>Clear the console log captured by agent-browser</td></tr>
    <tr><td><code>errors</code></td><td>Show captured page errors and uncaught JavaScript exceptions</td></tr>
    <tr><td><code>errors --clear</code></td><td>Clear the captured page error log</td></tr>
  </tbody>
</table>

Use `console --json` when object previews or raw CDP arguments matter for an automated diagnostic script. Use the default text output when an agent only needs to understand what the page logged.

## JavaScript dialogs

```bash
agent-browser dialog status
agent-browser dialog accept
agent-browser dialog accept "prompt text"
agent-browser dialog dismiss
```

By default, `alert` and `beforeunload` dialogs are automatically accepted so they do not block the agent. `confirm` and `prompt` dialogs still require explicit handling. Use `--no-auto-dialog` or `AGENT_BROWSER_NO_AUTO_DIALOG=1` to disable automatic handling.

When a dialog is pending, command responses include a `warning` field with the dialog type and message so agents can recover with `dialog accept` or `dialog dismiss`.

## DevTools and visual inspection

```bash
agent-browser highlight @e4
agent-browser highlight "#submit"
agent-browser inspect
```

`highlight` draws attention to an element in the live page, which is useful when running headed or when viewing the session through streaming or the dashboard. `inspect` opens Chrome DevTools for the active page through a local proxy while the daemon continues to accept agent-browser commands.

## Chrome trace capture

```bash
agent-browser trace start

agent-browser open https://example.com
agent-browser click @e3

agent-browser trace stop ./trace.json
```

`trace start` begins a Chrome DevTools trace. `trace stop [path]` ends tracing and saves a Chrome Trace Event JSON file. If no path is provided, agent-browser writes an auto-generated trace file under its temp directory.

Use [Profiler](/profiler) when you want curated performance categories and event counts. Use raw traces when you need a general Chrome trace for lower-level debugging.

## Timeouts

Standard operations such as clicks, fills, and waits time out after 25 seconds by default. The CLI waits at least 30 seconds for the daemon's reply, so the daemon reports its own timeout error before the CLI gives up on the socket. Set `AGENT_BROWSER_DEFAULT_TIMEOUT` in milliseconds to change the default:

```bash
export AGENT_BROWSER_DEFAULT_TIMEOUT=45000
```

Wait commands extend the CLI's read timeout to match their budget. Other commands keep the 30-second floor, so a value above 30000 can make a slow action outlive the CLI's read. Read-only commands such as `snapshot`, `url`, and `get text` are retried automatically. A command that changes the page or launches the browser is not re-sent after the daemon receives it, because it may already have run; it fails with code `outcome_unknown` instead.

When a command times out because the page stopped responding, for example a script stuck in `while(true){}`, it fails with code `page_wedged`. If agent-browser launched the browser and the next command also times out, agent-browser replaces the stuck tab with a blank one, so later commands work again after you navigate. A page that recovers in between keeps its tab. With `--cdp` or `--auto-connect`, the tab belongs to your browser and is left as is. The tab is also left as is when an action policy denies `tab_new` or `tab_close` or requires confirmation for them.

## Related tools

<table>
  <thead>
    <tr><th>Need</th><th>Use</th></tr>
  </thead>
  <tbody>
    <tr><td>Performance profile</td><td><a href="/profiler">Profiler</a></td></tr>
    <tr><td>Saved video artifact</td><td><a href="/recording">Video Recording</a></td></tr>
    <tr><td>Live browser stream</td><td><a href="/streaming">Streaming</a></td></tr>
    <tr><td>Install and environment diagnosis</td><td><a href="/installation#doctor">Doctor</a></td></tr>
  </tbody>
</table>
