Skip to main content
This guide covers common problems you might encounter and how to resolve them.

​
Selector Issues

Error Message:
Element not found: selector=".my-button"
Causes:
  1. The selector doesn’t match any element
  2. The element hasn’t loaded yet
  3. The element is in a shadow DOM
  4. The selector syntax is invalid
Solutions:Verify the selectorOpen the page in Chrome DevTools:
  1. Navigate to your URL
  2. Open Console (Cmd+Option+J on macOS)
  3. Run: document.querySelector('.my-button')
  4. If it returns null, the selector is wrong
Add a wait condition
[
  { "action": "wait", "selector": ".my-button", "timeout": 5000 },
  { "action": "click", "selector": ".my-button" }
]
Or use waitFor at the video level:
{
  "videos": {
    "my-demo": {
      "url": "https://example.com",
      "waitFor": ".my-button",
      "steps": [
        { "action": "click", "selector": ".my-button" }
      ]
    }
  }
}
Use text targeting instead
{ "action": "click", "text": "Submit" }
This finds any element containing “Submit” and is more resilient to markup changes.Check for dynamic contentIf content loads via JavaScript, add pauses:
[
  { "action": "pause", "ms": 1000 },
  { "action": "click", "selector": ".my-button" }
]
Error Message:
Element not found: text="Sign In"
Causes:
  1. Text doesn’t exist on page
  2. Text is split across multiple elements
  3. Text has different capitalization
  4. Text hasn’t loaded yet
Solutions:Check exact textText matching is exact and case-sensitive:
  • "Sign In" ≠ "sign in"
  • "Sign In" ≠ "Sign In" (extra space)
Verify in DevTools
document.body.innerText.includes("Sign In")
If this returns false, the text isn’t on the page.Use a selector instead
{ "action": "click", "selector": "button[type='submit']" }
Add a wait
[
  { "action": "wait", "text": "Sign In", "timeout": 5000 },
  { "action": "click", "text": "Sign In" }
]
Problem: Your selector or text matches multiple elements, and webreel clicks the wrong one.Solutions:Use ‘within’ to scope
{
  "action": "click",
  "text": "Delete",
  "within": ".modal"
}
This only searches within .modal, ignoring other “Delete” buttons.Make selector more specificInstead of:
{ "action": "click", "selector": "button" }
Use:
{ "action": "click", "selector": "form#login button[type='submit']" }
Use unique attributes
{ "action": "click", "selector": "[data-testid='submit-button']" }

​
Timing Issues

Problem: The recording executes too quickly, making it hard to follow.Solutions:Set a default delay
{
  "videos": {
    "my-demo": {
      "url": "https://example.com",
      "defaultDelay": 800,
      "steps": []
    }
  }
}
All steps wait 800ms after completing.Add per-step delays
[
  { "action": "click", "text": "Menu", "delay": 1200 },
  { "action": "click", "text": "Settings" }
]
Add pause steps
[
  { "action": "click", "text": "Submit" },
  { "action": "pause", "ms": 1500 },
  { "action": "click", "text": "Confirm" }
]
Problem: Recording starts before the page is ready.Solutions:Use waitFor
{
  "videos": {
    "my-demo": {
      "url": "https://example.com",
      "waitFor": ".main-content",
      "steps": []
    }
  }
}
Webreel waits up to 30 seconds for .main-content to appear.Add initial pause
{
  "steps": [
    { "action": "pause", "ms": 2000 },
    { "action": "click", "text": "Start" }
  ]
}
Wait for specific elements
[
  { "action": "wait", "selector": "#app[data-loaded='true']" },
  { "action": "click", "text": "Continue" }
]
Problem: Elements are animating when webreel tries to click them.Solutions:Add delays after navigation
[
  { "action": "navigate", "url": "/page" },
  { "action": "pause", "ms": 1000 },
  { "action": "click", "text": "Button" }
]
Wait for element and pause
[
  { "action": "wait", "selector": ".animated-element" },
  { "action": "pause", "ms": 500 },
  { "action": "click", "selector": ".animated-element" }
]

​
Binary Installation Problems

Error Message:
Failed to download Chrome
Solutions:Check network connectionWebreel downloads Chrome from the internet on first run. Verify you have an active connection.Retry installation
npx webreel install --force
The --force flag re-downloads even if Chrome already exists.Manual Chrome pathIf you have Chrome installed, you can point to it by setting an environment variable (this is an advanced workaround and may require code changes).Check disk spaceChrome requires ~300MB in ~/.webreel/. Verify you have sufficient space:
df -h ~
Error Message:
Failed to download ffmpeg
Solutions:Force reinstall
npx webreel install --force
Check platform supportWebreel downloads ffmpeg for:
  • macOS (Intel and Apple Silicon)
  • Linux (x64 and arm64)
  • Windows (x64)
Unsupported platforms must install ffmpeg manually and ensure it’s in PATH.Verify downloadCheck if ffmpeg exists:
ls -lh ~/.webreel/ffmpeg
If the file is 0 bytes or corrupted, delete and reinstall:
rm -rf ~/.webreel/ffmpeg
npx webreel install
Error Message:
EACCES: permission denied
Solutions:Fix permissions
chmod +x ~/.webreel/chrome/chrome
chmod +x ~/.webreel/ffmpeg
Reinstall
rm -rf ~/.webreel
npx webreel install

​
Recording Issues

Causes:
  1. Page didn’t load
  2. Viewport is wrong size
  3. Chrome crashed during recording
Solutions:Use preview mode first
npx webreel preview
This runs in a visible browser so you can see what’s happening.Check verbose output
npx webreel record --verbose
Look for errors in the step execution.Verify the URL loadsOpen the URL in your regular browser. If it doesn’t load there, it won’t load in webreel.Check viewport sizeSome pages break at unusual sizes. Try standard dimensions:
{
  "viewport": { "width": 1920, "height": 1080 }
}
Cause: Recording stops before animations complete.Solution: Add a final pause:
{
  "steps": [
    { "action": "click", "text": "Submit" },
    { "action": "pause", "ms": 2000 }
  ]
}
This ensures the video captures the final state.
Cause: Cursor theme or size is incompatible with page styles.Solutions:Increase cursor size
{
  "theme": {
    "cursor": {
      "size": 32
    }
  }
}
Use high-contrast cursorProvide a custom SVG with a bright color:
{
  "theme": {
    "cursor": {
      "image": "./bright-cursor.svg"
    }
  }
}
Check z-indexIf your page has elements with z-index over 999999, the cursor may be hidden behind them. This is expected behavior; the cursor is still functional.
Error Message:
Step 3 (click) failed: ...
Solutions:Use verbose mode
npx webreel record --verbose
This shows exactly which step failed and why.Test steps incrementallyComment out later steps and add them back one at a time:
{
  "steps": [
    { "action": "click", "text": "Step 1" },
    { "action": "click", "text": "Step 2" }
    // { "action": "click", "text": "Step 3" }
  ]
}
Record after each addition to isolate the problematic step.Check browser consoleRun in preview mode and check the browser console for JavaScript errors from your page.

​
Configuration Issues

Error Message:
Config file not found: webreel.config.json
Solutions:Check working directory
pwd
ls -la webreel.config.json
Webreel looks for webreel.config.json in the current directory.Specify config path
npx webreel record -c path/to/config.json
Create config
npx webreel init
Error Message:
Unexpected token } in JSON
Causes:
  • Trailing comma in last array/object item
  • Missing quotes around keys
  • Missing comma between items
  • Unescaped quotes in strings
Solutions:Validate config
npx webreel validate
This reports syntax errors with line numbers.Use IDE validationThe $schema field enables autocomplete and validation in VS Code and other editors:
{
  "$schema": "https://webreel.dev/schema/v1.json"
}
Common fixes:Remove trailing commas:
// Wrong
{
  "name": "value",
}

// Right
{
  "name": "value"
}
Escape quotes in strings:
// Wrong
{ "text": "Click "Submit"" }

// Right
{ "text": "Click \"Submit\"" }
Error Message:
Invalid configuration: action is required
Cause: Config doesn’t match the schema.Solutions:Check required fieldsEvery step needs an action field:
{ "action": "click", "text": "Button" }
Validate
npx webreel validate
Check documentationRefer to the Actions Reference for required fields for each action.

​
Verbose Mode

Use verbose mode to debug issues: 
npx webreel record --verbose
This outputs:
  • Each step as it executes: [step 0] pause 500ms
  • Element searches: click text="Submit"
  • Timing information
  • Error details with stack traces
Example output: 
Recording: my-demo
[step 0] pause 500ms
[step 1] click text="Get Started"
[step 2] key "cmd+s"
[step 3] pause 1000ms
Done: videos/my-demo.mp4
If a step fails, you’ll see exactly which one and why.

​
Preview Mode for Debugging

Preview mode runs steps in a visible browser without recording: 
npx webreel preview
Use this to:
  • Verify selectors work
  • Check timing and delays
  • See JavaScript errors in DevTools
  • Test steps interactively
Preview is much faster than recording and lets you open DevTools to inspect the page state.

​
Dry Run Mode

Print the resolved configuration without executing: 
npx webreel record --dry-run
This shows:
  • All videos in the config
  • Resolved URLs and viewport sizes
  • All steps with descriptions
  • Inherited values from top-level config
Use this to verify your config is structured correctly before recording.

​
File Path Issues

Problem: url: "./web/index.html" fails to load.Solutions:Check relative pathPaths are relative to the config file:
project/
  webreel.config.json
  web/
    index.html

{ "url": "./web/index.html" }
Use absolute file:// URLs
{ "url": "file:///Users/you/project/web/index.html" }
Check file exists
ls web/index.html
Problem: Custom cursor doesn’t appear.Solutions:Check file pathPath is relative to config file:
{
  "theme": {
    "cursor": {
      "image": "./cursor.svg"
    }
  }
}
Validate SVG syntaxOpen the SVG in a browser to verify it’s valid.Check file permissions
ls -l cursor.svg

​
Getting Help

If you’re still stuck:
  1. Check examples: Browse the examples directory for similar use cases
  2. Search issues: Look for similar problems in GitHub Issues
  3. Run with verbose: Always include verbose output when reporting issues
  4. File an issue: Open a new issue with:
    • Your config file
    • Verbose output
    • Expected vs actual behavior
    • Operating system and Node version

​
Next Steps

API Reference

Complete reference for all actions

Examples

Browse working examples

Configuration

Full configuration reference

Build docs developers (and LLMs) love

Get started for freeTalk to us