Back to docs

Troubleshooting

Solutions for common CBrowser issues.

Installation Issues

"playwright: command not found"

Problem: Playwright browsers not installed.

Solution:

npx playwright install chromium

"EACCES: permission denied"

Problem: npm permission issues on Linux/macOS.

Solution:

# Option 1: Use npx (recommended)
npx cbrowser --version

# Option 2: Fix npm permissions
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g cbrowser

"Node version not supported"

Problem: CBrowser 20 requires Node.js 20.9 or newer. Stay on cbrowser 19.x if you need Node 18.

Solution:

# Check version
node --version

# Update with nvm
nvm install 20
nvm use 20

Browser Issues

"Browser closed unexpectedly"

Problem: Browser crashes during operation.

Possible causes:

  1. Memory: Browser ran out of memory
  2. Timeout: Operation took too long
  3. GPU: Graphics driver issue

Solutions:

# Raise the navigation timeout (ms)
CBROWSER_TIMEOUT=120000 \
  npx cbrowser navigate \
  https://example.com

# Disable GPU (Linux)
PLAYWRIGHT_CHROMIUM_ARGS=\
"--disable-gpu" npx cbrowser ...

# Use different browser
npx cbrowser navigate \
  --browser firefox \
  https://example.com

"Display not found" / "Cannot open display"

Problem: No display available (headless server).

Solution:

# Force headless mode
CBROWSER_HEADLESS=true npx cbrowser navigate "https://example.com"

# Or install virtual display (Linux)
sudo apt-get install xvfb
xvfb-run npx cbrowser navigate "https://example.com"

Browser hangs on certain sites

Problem: Page never finishes loading.

Solutions:

# Raise the navigation timeout (ms)
CBROWSER_TIMEOUT=60000 npx cbrowser \
  navigate "https://slow-site.com"

# Some sites block automation: try a
# different user agent (configure it
# in .cbrowserrc.json)

Selector Issues

"Element not found"

Problem: CBrowser can't find the element.

Solutions:

  1. Check the page loaded: Add a wait or verify the URL first
go to https://example.com
wait 2 seconds
click "Login"
  1. Use more specific description:
# Instead of
click "Submit"

# Try
click "Submit button in the login form"
  1. Check if element is in iframe:
# CBrowser doesn't automatically switch to iframes
# The element might be inside an iframe
  1. Clear selector cache:
npx cbrowser heal clear

"Element not interactable"

Problem: Element exists but can't be clicked/filled.

Causes:

  • Element is hidden
  • Element is disabled
  • Another element overlays it
  • Element is still animating

Solutions:

# Add wait
wait 1 second
click "Button"

# Or wait for specific condition
wait for "Loading" to disappear
click "Button"

Self-healing not finding alternatives

Problem: Smart-click fails even with retries.

Solutions:

  1. Check heal stats:
npx cbrowser heal stats
  1. Clear corrupted cache:
npx cbrowser heal clear
  1. Increase retries:
npx cbrowser smart-click "Button" --max-retries 5

Test Issues

Tests pass locally but fail in CI

Common causes:

  1. Timing differences: CI is slower
# Add explicit waits
wait 2 seconds
  1. Screen size differences:
# Pin the page size
# (default: 1920x1080)
npx cbrowser test-suite tests.txt \
  --viewport 1920x1080
  1. Missing browsers in CI:
# GitHub Actions
- run: npx playwright install chromium

Flaky tests despite fixes

Problem: Tests still intermittently fail.

Solutions:

  1. Run more iterations:
npx cbrowser flaky-check tests.txt --runs 20

  1. Check per-step analysis: Find exactly which step is flaky

  2. Add defensive waits:

click "Save"
wait for "Saved successfully" to appear
verify page contains "Saved"
  1. Avoid timing-dependent assertions:
# Bad - depends on exact count
verify page contains "10 results"

# Better - resilient to changes
verify page contains "results"

Test repair suggestions don't work

Problem: AI repair suggestions have low confidence or don't fix the issue.

Solutions:

  1. Run without auto-apply first: Review suggestions manually
npx cbrowser repair-tests tests.txt
# Review suggestions, then:
npx cbrowser repair-tests tests.txt --auto-apply
  1. Page might have changed significantly: Re-analyze the page
npx cbrowser analyze "https://example.com/page"
  1. Regenerate tests from scratch:
npx cbrowser generate-tests "https://example.com/page"

Session Issues

"Session not found"

Problem: Saved session doesn't exist.

Solution:

# List available sessions
npx cbrowser session list

# Check session directory
ls ~/.cbrowser/sessions/

Session loads but I'm logged out

Problem: Session expired or cookies cleared.

Causes:

  • Session cookies expired
  • Site invalidated the session
  • Different browser fingerprint

Solutions:

  1. Re-save the session after logging in again

  2. Check session age:

npx cbrowser session list  # Shows last used date
  1. Some sites require fresh sessions - save more frequently

Page state not kept between commands

Problem: The page you left in one command is gone in the next.

Solution: The persistent profile is on by default, so cookies, storage and the last URL carry over (--no-persistent turns it off). Each command is its own process, though, so the next command reloads the page. To keep one live page, start the daemon:

npx cbrowser daemon start
npx cbrowser navigate \
  https://example.com
npx cbrowser fill email \
  "[email protected]"
npx cbrowser daemon stop

While the daemon runs, navigate, click, fill, hover, type, press, keyboard, screenshot, extract, run, scroll, evaluate, capture, har, network and console use its browser. Commands that would open a second browser on its profile (for example script, ai, explore, a11y, perf and visual) refuse until you stop it.

MCP Issues

Tools not appearing in Claude

Problem: CBrowser tools don't show in Claude Desktop.

Solutions:

  1. Check config syntax: Ensure valid JSON
{
  "mcpServers": {
    "cbrowser": {
      "command": "npx",
      "args": ["cbrowser", "mcp-server"]
    }
  }
}

  1. Restart Claude Desktop completely (not just close window)

  2. Check CBrowser is installed:

npx cbrowser --version
  1. Check config file location:
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

MCP connection timeout

Problem: Claude can't connect to CBrowser server.

Solutions:

  1. Increase timeout in config:
{
  "mcpServers": {
    "cbrowser": {
      "command": "npx",
      "args": ["cbrowser", "mcp-server"],
      "env": {
        "CBROWSER_TIMEOUT": "120000"
      }
    }
  }
}
  1. Check for conflicting processes:
ps aux | grep cbrowser

Performance Issues

Commands are slow

Solutions:

  1. Use the daemon: it keeps one browser open, so later commands skip the browser launch:
npx cbrowser daemon start
  1. Reduce screenshots:
# Only screenshot when needed
go to https://example.com
# Don't: take screenshot after every step
verify page contains "text"
take screenshot  # Only at end
  1. Use headless mode (default, fastest)

High memory usage

Problem: Browser consumes too much RAM.

Solutions:

  1. Close browser when done:
await browser.close();

  1. Don't use persistent mode for long operations

  2. Reduce concurrent operations

Getting Help

If none of these solutions work:

  1. Check existing issues: GitHub Issues

  2. Create detailed bug report with:

    • CBrowser version (npx cbrowser --version)
    • Node.js version (node --version)
    • Operating system
    • Full error message
    • Minimal reproduction steps

  3. Include relevant logs:

DEBUG=cbrowser:* npx cbrowser ...

Copyright: (c) 2026 Alexa Eden.

License: MIT License

Contact: [email protected]

From the Blog