# Browser problems Source: https://docs.ideharmony.com/troubleshooting/browser 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:** 1. The agent is driving a different session than the pane you are watching. 2. 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](/docs/troubleshooting/gpu-and-terminal-rendering). --- ## The page loads but the agent cannot interact **Likely causes** 1. Wrong surface — see above. 2. The element is inside a frame or shadow root the selector does not reach. 3. 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](/docs/security). --- ## The browser will not start **Likely causes** 1. Port allocation failure. 2. The profile is locked by a previous run that did not exit cleanly. **Safe diagnostic** ```powershell harmony 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 ```powershell harmony 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. ## Related - [Browser surface](/docs/desktop/browser) - [Security overview](/docs/security) - [GPU and terminal rendering](/docs/troubleshooting/gpu-and-terminal-rendering)