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 requires Node.js 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:

# Increase timeout
npx cbrowser navigate "https://example.com" --timeout 120000

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

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

"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:

# Increase timeout
npx cbrowser navigate "https://slow-site.com" --timeout 60000

# Some sites block automation - try with different user agent
# (Configure 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:
# Set consistent viewport
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

Cookies not persisting

Problem: Changes not saved between commands.

Solution: Use persistent mode:

npx cbrowser navigate "https://example.com" --persistent
npx cbrowser fill "email" "[email protected]" --persistent
# Both commands share the same browser context

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 persistent mode:
npx cbrowser navigate "..." --persistent
  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