Browser problems
A browser surface will not load, an agent cannot interact with it, or a session vanished between runs.
Before diagnosing anything: there are two browser things, and confusing them explains most problems here.
| Thing | What it is |
|---|---|
| Browser pane | The embedded surface you are looking at |
| Driven session | A separately-controlled session used for automation |
An agent driving a browser is usually not driving the pane you have open. "The agent can't see what I can see" is normally this, not a failure.
An agent says a page is empty and I can see content
Two candidates, in order:
- The agent is driving a different session than the pane you are watching.
- GPU compositing is producing a blank capture while the screen renders fine.
Safe diagnostic: ask the agent to report the URL it is on. If it differs from your pane, that is the answer.
IMPORTANT
Suspect capture or session mismatch before concluding the agent is confused. Both are far more common than a model hallucinating an empty page.
See GPU and terminal rendering.
The page loads but the agent cannot interact
Likely causes
- Wrong surface — see above.
- The element is inside a frame or shadow root the selector does not reach.
- The page changed between the agent reading it and acting.
Repair: have the agent re-read the page immediately before acting rather than acting on an earlier observation. Pages move.
A signed-in session disappeared between runs
Likely cause: a different partition.
Browser surfaces use partitioned profiles, so cookies and storage belong to the partition, not to "the browser". A surface created in a different context starts clean — correctly.
IMPORTANT
Partitioning is isolation between surfaces, not anonymity. A session you establish in a partition persists in that partition, including for agents that later use it.
An agent reached something I did not expect
This is the risk worth taking seriously rather than treating as a bug.
An agent driving a browser can reach anything that browser can reach — including any site signed in within that partition. There is no sandbox between the agent and your authenticated sessions.
Repair: use a clean partition for agent work. Do not hand an agent a browser carrying your own logins unless that is specifically the task.
SECURITY
Everything a browser surface loads is untrusted input. A page can contain text written to steer an agent reading it. Approval gates exist for exactly this — see security overview.
The browser will not start
Likely causes
- Port allocation failure.
- The profile is locked by a previous run that did not exit cleanly.
Safe diagnostic
nala doctor
Repair: close the workspace fully and reopen. If it persists, restart the app so stale profile locks are released.
When not to retry: do not delete browser profile data to clear a lock without checking what is in it. Sessions you rely on live there.
Screenshots are stale
Likely cause: captured before the page settled.
Repair: have the agent wait for a specific element rather than a fixed delay. Fixed delays are either too short on a slow load or wasted on a fast one.
Collecting evidence
nala doctor --json
Include which surface — pane or driven session — and the URL.
WARNING
Browser screenshots capture whatever is on screen, including any signed-in account. Check before sharing.