FAQ & troubleshooting

Real failures from real sites, and what to do about each one.

ffmpeg is missing after a clean install

Your npm config sets ignore-scripts=true, so ffmpeg-static never downloaded its binary. Reinstall with --ignore-scripts=false, or set PLAYHEAD_FFMPEG to an ffmpeg you already have. playhead doctor reports this before a render does.

The first render fails with “Executable doesn’t exist”

The capture browser is a separate download: npx playwright install chromium. Only chromium is needed, not the full browser set.

A cookie banner is in every frame

Dismiss it before recording starts, with a top-level setup: block. Those steps run with the camera off:

setup:
  - click: 'role=button[name="Close"]'

The video shows a loading spinner

Capture reached the step before the app finished hydrating. Add a structured wait rather than a sleep — and note that verification now warns when a frame’s content region is blank, which is how you catch this without watching:

- wait: { for: 'testid=main-content', state: visible, timeout: 20000 }

“No visible effect” on a click that clearly works

The app was already in the state the click produces — clicking “fit” when the view is already fitted, or re-selecting the active tab. Reorder so the action has something to change (zoom first, then fit), or drop the step.

The page never finishes loading

Ad- and tracker-heavy sites often never fire the browser’s load event. Tell Playhead not to wait for it:

app:
  navigation: domcontentloaded

My app is built from web components and explore finds nothing

Explore reads through open shadow roots, so most component-based apps are fully addressable. Closed shadow roots are invisible to explore and to capture alike — if an element cannot be seen, it cannot be filmed either.

The video looks unstyled, like raw HTML

Some sites serve a stripped, CSS-free page to anything that looks like a crawler. Playhead presents the same user agent a normal Chrome sends, so this should not happen — if it does, check whether your CDN or prerender layer is gating on something else.

Verification passed but the video is of the wrong page

Add an expect that only your app can satisfy. Without one, nothing anchors the spec: a proxy block page or login wall has live pixels and sane pacing, so every check passes on footage of the wrong thing.

My session expired mid-suite

Re-run playhead login to refresh the stored session, and put assertLoggedIn in the spec so a stale session fails immediately instead of filming the login page.