Debug Browser Use failures with a local trace timeline

Why this exists

When a Browser Use run fails late in a task, a stack trace usually tells you which exception happened. It often does not show what the agent saw, which URL it was on, which model decision selected the target, or whether the wrong assumption came from an earlier step.

BrowserTrace keeps that missing context in a local SQLite database plus screenshot files. No signup or cloud service is required.

Try it before wiring Browser Use

uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace doctor
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace demo
uvx --from "browsertrace[ui] @ git+https://github.com/aaronlab/browsertrace@v0.1.15" browsertrace

Open http://127.0.0.1:3000, then inspect demo: checkout agent fails on disabled button. From a source checkout, python examples/browser_use_callback_demo.py records Browser Use-shaped callback steps without installing Browser Use.

Attach it to a Browser Use agent

from browser_use import Agent
from browsertrace import Tracer
from browsertrace.integrations.browser_use import attach_tracer

tracer = Tracer()
agent = Agent(task="...", llm=ChatOpenAI(model="gpt-4o"))

with attach_tracer(agent, tracer, name="browser-use checkout run"):
    await agent.run()

The adapter hooks Browser Use step callbacks and records URL, screenshot, action summary, compact browser-state context, model thought/actions, status, and errors into the same local timeline.

For adapter field requests, use the Browser Use feedback issue and include the Browser Use version, failure shape, and which context your logs missed.

Callback compatibility

attach_tracer supports Browser Use agents that expose register_new_step_callback, plus older or forked agents with on_step_start, on_step, or _new_step_callback attributes.

Current Browser Use examples may also pass on_step_start or on_step_end directly to agent.run(...). For that run-hook-only path, use create_run_hooks:

from browsertrace import Tracer
from browsertrace.integrations.browser_use import create_run_hooks

tracer = Tracer()
hooks = create_run_hooks(tracer, name="browser-use checkout run")

with hooks:
    await agent.run(on_step_start=hooks.on_step_start, on_step_end=hooks.on_step_end)

The run-hook helper reads Browser Use history and browser-session summaries when they are available, then records the latest thought, action, extracted content, URL, title, tabs, and screenshot flag into the same local timeline. If your Browser Use version exposes a different hook shape, comment on issue #11 with the version and callback surface.

Share only what is safe

browsertrace list
browsertrace export <run_id> -o full.html
browsertrace export <run_id> --redact -o public.html
browsertrace export <run_id> --public -o public.html

The full export includes model input, model output, screenshots, and URLs. Use --public to omit all three sensitive fields before public sharing, or use individual redaction flags when you want to keep some fields visible.

Troubleshooting Browser Use traces

Could not attach to this Agent

BrowserTrace first tries register_new_step_callback, then common step callback attributes used by older or forked Browser Use agents. If your version exposes a different hook, comment on issue #11 with the Browser Use version and callback surface.

No screenshots appear

Some Browser Use states do not expose a screenshot for every step. BrowserTrace still records the URL, action summary, model thought/actions, status, and error when those fields are available.

The trace includes private page or prompt data

Keep the full trace local. Before attaching anything to a public issue or community post, run browsertrace export <run_id> --public -o public.html to omit prompt/model I/O, screenshots, and URLs.

What to inspect first

1. Did the screenshot match the model's assumption?
2. Did the selected action target the right element?
3. Did the URL change earlier than expected?
4. Did the model output mention a selector or label that was stale?
5. Was the red step wrong, or did an earlier step poison the state?