Guides

Troubleshooting

What the messages mean and what to do.

The capture stops at a step#

Message	What to do
`cannot load http://…: net::ERR_CONNECTION_REFUSED`	Start the dev server, or fix `browser.url`.
`target not actionable (not found)`	Check the target with `targets --after <the step before>`.
`target not actionable (covered)`	Something lies over it: a dialog, a cookie banner, a toast. Close it first, or wait for it to go.
`target not actionable (moving)`	It was still animating: wait for the page to settle first.
`wait timed out after 10 s`	The text never showed, or showed differently. Raise `timeout` on the step, or wait for something else.
`invalid CSS selector "…"`	It is another tool's syntax (`:has-text()`, `text=`, `:contains()`, XPath) or an id that starts with a digit. Use `{ text: … }`, or `[id="123"]`.
`the page stopped answering`	A script on the page never ends, or a promise it awaits never settles.

capture also warns, without stopping, when the server answered a page with an error (404, 500…), which the video then shows: check the path (a goto from / leaves browser.url's own path); and when a field does not hold the typed text at the end (a mask, a length limit, a number field).

The partial take is kept in .browser-clip/takes/<key>-failed/ for a look.

The video looks wrong#

A step did nothing: look at the contact sheet (sheet); the frame after the step shows what the page did.
The camera frames the wrong thing: still --at <marker> --director draws the camera's view on the whole frame. Pin a shot, or use camera: static.
The pointer sits over the page: it fades out after resting 3 s (cursor.hide).
"the browser stalled on input": the browser held a pointer move or a key for a moment (a busy GPU, for example); the video leaves that time out, so nothing shows.

Sound and video#

No sound in the studio: browsers start sound after a click or a key press on the page.
No sound in the MP4: check typing.sound and typing.volume; a browser without an AAC or Opus encoder writes no track, and render says so.
The MP4 does not open in an editor: a plain Chromium may not encode H.264, and --deterministic writes VP9. Use Chrome or Edge for H.264.

Source: docs-src/pages/guides/troubleshooting.md · browser-clip 0.1.0