Troubleshoot browser automation
Start with beaconctl browser.info for the installed engine's capabilities and beaconctl skill show for matching usage instructions.
The shell cannot find beaconctl
Open Beacon.app once, then use the installation guide to check the shortcut or invoke the CLI inside the app. If you moved the app, launch it again to refresh its managed shortcut.
The agent no longer controls its tab
control.user_owned means the space is unavailable for agent actions. Stop sending browser actions and use the recovery that matches its state:
- After Take Over, the person chooses Resume Agent, or dismisses the takeover message before declaring another task.
- After Stop, the person dismisses the stopped-state message before starting another task.
- After task completion, declare or join the task again to continue.
Do not automatically claim a task after a person takes over or stops work.
A reference no longer resolves
Read a new snapshot and use a reference from that result. References belong to the current frame document and must appear in the latest exported snapshot. Navigation and subtree changes can invalidate an earlier reference.
Native input fails in the background
The window must stay open and non-minimized. The app can remain behind other apps, but hidden or minimized windows can return input.window_not_active. Helpers select the working tab for native input; low-level commands require page.select first.
WebKit suppresses native hover while inactive. Synthetic page.hover works in the background, but does not create native CSS hover or trusted hover events.
A site is signed out
Confirm the selected login profile and verify that cookie import succeeded. Some sites depend on localStorage, device-bound credentials, or other state that does not transfer. Sign in within the browser when needed.
A Chromium script fails
Public WKWebView has no CDP endpoint; CDP calls return engine.unsupported. Snapshots use DOM semantics, not Chromium's accessibility tree. Pre-existing closed shadow roots can be opaque, and network idle observes page requests and resource completion rather than all browser traffic.
If page evaluation times out, it can still have late effects. Inspect the page before retrying an action that might submit or change something.