Common Issues

Fix the most common Rollberry problems, including missing FFmpeg, old Node.js versions, localhost timing issues, and render project errors.

FFmpeg not found#

Symptom: The command fails before encoding starts and reports that FFmpeg is missing.

Fix: Install ffmpeg and make sure it is on PATH.

# macOS
brew install ffmpeg
 
# Ubuntu
sudo apt install ffmpeg
 
# Windows
winget install ffmpeg

Node.js version too old#

Symptom: The package fails to install or run correctly.

Fix: Upgrade to Node.js 24.12.0 or later.

node --version

Chromium failed to install or launch#

Symptom: Rollberry cannot start Chromium.

Fix: Retry the run once, then install Playwright Chromium manually if needed.

npx playwright install chromium

Localhost server is not ready#

Symptom: Capturing http://localhost:3000 fails with connection errors.

Fix: Increase the timeout and use a stronger wait condition.

npx rollberry capture http://localhost:3000 \
  --out ./artifacts/local.mp4 \
  --timeout 60000 \
  --wait-for selector:#app

First frame is blank or incomplete#

Symptom: The video starts before the page is visually ready.

Fix: Use --wait-for selector:<css> or --wait-for ms:<n>.

npx rollberry capture https://example.com \
  --out ./artifacts/demo.mp4 \
  --wait-for selector:main

Overlays still appear in the output#

Symptom: Cookie banners or chat widgets cover the capture.

Fix: Add the correct --hide-selector entries and verify them with debug frames.

npx rollberry capture https://example.com \
  --out ./artifacts/demo.mp4 \
  --hide-selector "#cookie-banner" \
  --debug-frames-dir ./artifacts/debug-frames

Output already exists#

Symptom: Rollberry refuses to write the target output path.

Fix: Re-run with --force.

npx rollberry capture https://example.com \
  --out ./artifacts/demo.mp4 \
  --force

The same applies to render when a configured output already exists.

Page height was truncated#

Symptom: The manifest contains scroll_height_truncated, or the video does not reach the full page length.

Fix: Split the page into scenes, shorten the recording goal, or redesign the workflow around render.

The current implementation caps measured scroll height at 30000px.

Too many frames#

Symptom: Rollberry reports that the frame count exceeds the maximum.

Fix: Reduce one or more of:

--fps
--duration
--page-gap
the number of scenes or outputs

The current implementation caps total frames at 36000.

Render project validation failed#

Symptom: npx rollberry render exits before capture begins with a project-file validation error.

Fix: Check:

schemaVersion is 1
scenes is non-empty
every action type is supported
every timeline step has the right target fields
output names are unique

Also validate your file against rollberry.project.schema.json in your editor.

Crossfade render issues#

Symptom: Crossfade-based renders fail with probe warnings.

Fix: Ensure your FFmpeg installation also includes ffprobe, because crossfade composition depends on probe-backed clip durations.

ffprobe -version

Debugging checklist#

When a run still fails, inspect artifacts in this order:

<out>.manifest.json
<out>.log.jsonl
debug frames if the issue is visual
*.render-summary.json for project renders