Troubleshooting

The toolbar is unavailable

Confirm the page route is enabled, the extension has site permission, and the page was refreshed after loading a new extension build. Browser-extension content scripts cannot always update an already-open page without a reload.

The agent cannot see the Queue

Confirm the local server is running and the MCP client points to the expected loopback endpoint. Check the extension compatibility notice if server and extension builds come from different revisions.

Run waypoint status first. If the server is stopped, run waypoint start and check again. If it fails to start, inspect waypoint logs for the reported error. Reconnect your agent’s MCP tools after correcting its configuration.

If tools connect but return no Annotations, compare the requested URL with the browser address, especially its port and path. A page or view filter can exclude work elsewhere in the project; try the project root. Save a small test Annotation at the intended URL and read again.

waypoint status
waypoint logs

The agent stopped noticing new feedback

Ask the agent to read the Queue again for the explicit app URL. Watch delivers activity, but it cannot guarantee that your coding-agent harness wakes an idle agent or keeps scheduling reads while the agent edits.

If you use waypoint watch, keep its terminal process running and inspect any reported connection error. See Agent Setup for the foreground consumer and resumption options. A quiet Watch does not by itself mean an Annotation was deleted.

A preview is gone or the source looks unchanged

Element Edits and Active Variants are browser presentations, not proof of a permanent source change. Ask the agent whether it implemented and verified the request in your repository.

For Variants, inspect the Queue for a Keep or cancellation decision before asking the agent to restore anything. Cancellation intentionally removes the comparison; recreating it would reverse that decision. If the original Target no longer exists, open the Annotation from the Queue and ask the agent to inspect the changed page structure.

A screenshot misses image pixels

Image capture can be affected by resource decoding, cross-origin rules, canvas restrictions, or unsupported source types. Preserve the Annotation and report the capture context; do not assume a retrieved crop contains every resource merely because metadata exists.