Skip to content

Troubleshooting

Jump to bottom
Kumak edited this page Nov 22, 2025 · 2 revisions

Troubleshooting

Common issues and solutions.

Session Issues

"Daemon already running"

Symptom: Can't start a new session.

Solution:

bdg cleanup --force
# Or if that doesn't work:
bdg cleanup --aggressive

"Session not found" / "No active session"

Symptom: Commands fail with exit code 83 (Resource Not Found).

Solution:

# Start a session first
bdg example.com

# Then run commands
bdg dom query "button"

Stale Session Files

Symptom: bdg thinks a session is running but Chrome is closed.

Solution:

bdg cleanup --force
# Check status
bdg status

Chrome Issues

"Chrome failed to launch"

Symptom: Exit code 100.

Causes & Solutions:

  1. Chrome not installed:

    # macOS
brew install --cask google-chrome

# Linux
sudo apt install google-chrome-stable

  2. Port in use:

    # Use different port
bdg example.com --port 9223

  3. Permission denied:

    # Check Chrome binary
ls -la /Applications/Google\ Chrome.app/

Chrome Processes Lingering

Symptom: Multiple Chrome processes after stopping bdg.

Solution:

bdg cleanup --aggressive
# Or manually:
pkill -f "chrome.*remote-debugging"

Headless Mode Issues

Symptom: Headless Chrome behaves differently.

Tips:

  • Some sites detect headless mode
  • Use --user-data-dir for persistent profile
  • Check bdg status --verbose for Chrome flags

Connection Issues

"CDP connection failed"

Symptom: Exit code 101.

Causes:

  1. Chrome closed unexpectedly
  2. WebSocket disconnected
  3. Network issues

Solution:

bdg status --verbose
# If Chrome is dead:
bdg cleanup --force
bdg example.com

"CDP timeout"

Symptom: Exit code 102.

Solutions:

  1. Page is slow - wait longer:

    bdg example.com --timeout 60

  2. Skip page readiness:

    bdg example.com --no-wait

DOM Issues

"Element not found"

Symptom: Exit code 83.

Debugging:

# Check what's on the page
bdg dom query "*" --json | jq '.count'

# Try broader selector
bdg dom query "button"
bdg dom query "[type=submit]"

# Check if page loaded
bdg dom eval "document.readyState"

Cached Index Invalid

Symptom: "Index out of range" after query.

Cause: Page changed since last query.

Solution:

# Re-run query to refresh cache
bdg dom query "button"
# Then use new indices
bdg dom get 0

Semantic Output Shows "(inferred from DOM)"

Not an error! This means Chrome's accessibility tree didn't have data for the element, so bdg inferred the role from HTML. The output is still valid and usable.

Network Issues

No Network Data

Symptom: bdg peek --network shows empty.

Causes:

  1. Session just started - make some requests
  2. Page loaded before session started

Solution:

# Navigate to trigger requests
bdg cdp Page.reload
bdg peek --network

Missing Response Bodies

Symptom: Response bodies are null.

Causes:

  1. Binary content (images, etc.)
  2. Large responses (> 5MB default)
  3. Streaming responses

Solution:

# Increase body size limit
bdg example.com --max-body-size 10

Platform Issues

Windows: "Socket not found"

Cause: Unix sockets don't work on native Windows.

Solution: Use WSL:

wsl
bdg example.com

macOS: Permission Denied

Symptom: Can't access Chrome or write files.

Solutions:

  1. Grant Terminal full disk access in System Preferences
  2. Check ~/.bdg/ directory permissions: 
    ls -la ~/.bdg/
chmod 755 ~/.bdg/

Exit Code Reference

Code Meaning Action
0 Success Continue
1 Generic error Check stderr
80 Invalid URL Fix URL format
81 Invalid arguments Check command syntax
82 Permission denied Check file/directory permissions
83 Resource not found Check selector/resource exists
84 Resource already exists Remove duplicate or use different name
85 Resource busy Resource is locked, wait or cleanup
86 Daemon already running Run bdg cleanup --force
100 Chrome launch failed Check Chrome installation
101 CDP connection failed Check Chrome is running
102 CDP timeout Increase timeout or use --no-wait
103 Session file error Check ~/.bdg/ permissions
104 Unhandled exception Report bug with details
105 Signal handler error Restart session
110 Software error Check logs, report bug

Additional Issues

Chrome Version Incompatibility

Symptom: CDP commands fail with unexpected errors.

Solution:

# Check Chrome version
google-chrome --version  # Linux
/Applications/Google\ Chrome.app/Contents/MacOS/Google\ Chrome --version  # macOS

# Update to latest stable Chrome
brew upgrade --cask google-chrome  # macOS

SSL Certificate Errors

Symptom: Can't connect to HTTPS sites with self-signed certificates.

Solution:

# Add Chrome flag to ignore cert errors (use with caution)
bdg https://localhost:3000 --chrome-ws-url "ws://localhost:9222/..."
# Or use Chrome's --ignore-certificate-errors flag manually

Memory Issues with Long Sessions

Symptom: Chrome becomes slow or crashes during long sessions.

Solutions:

  1. Increase Chrome memory limits (advanced)
  2. Restart session periodically: 
    bdg stop
bdg cleanup --force
bdg example.com
  3. Use --compact to reduce memory usage: 
    bdg example.com --compact

CORS Issues

Symptom: Local file:// URLs or CORS errors.

Workaround:

# For local files, use a local server instead
python3 -m http.server 8000
bdg localhost:8000

# CORS errors are browser-enforced, bdg can't bypass them
# Use a development proxy or CORS-enabled server

Getting Help

  1. Check bdg --help for command syntax
  2. Use bdg status --verbose for diagnostics
  3. Search existing issues
  4. Open a new issue with:
    • bdg version (bdg --version)
    • Node.js version (node --version)
    • OS and version
    • Full error output
    • Steps to reproduce

Clone this wiki locally