Skip to main content

​
Diagnostic Commands

​
Check Session Status

bdg status
Basic output: 
Session Status: Active
Worker PID:     12345
Chrome PID:     12346
Target URL:     http://localhost:3000/
Uptime:         5m 23s

​
Verbose Diagnostics

bdg status --verbose
Includes Chrome diagnostics: 
Session Status: Active
Worker PID:     12345
Chrome PID:     12346
Target URL:     http://localhost:3000/
Uptime:         5m 23s

Chrome Diagnostics:
Binary:           /usr/bin/google-chrome
Port:             9222
Installations:    2 found
  [1] /usr/bin/google-chrome
  [2] /snap/bin/chromium

​
Clean Up Stale Sessions

bdg cleanup
With options: 
bdg cleanup --force        # Force cleanup even if session appears active
bdg cleanup --aggressive   # Kill all Chrome processes
bdg cleanup --remove-output # Also remove session.json

​
Common Issues

​
Session Already Running

Error: 
bdg localhost:3000
# Error: Session already running (PID: 12345)
# Suggestion: Stop current session with: bdg stop
Exit Code: 84 (RESOURCE_ALREADY_EXISTS) Solutions: 
bdg stop
bdg localhost:3000
If bdg stop hangs or fails:
bdg cleanup --force
bdg localhost:3000
If session is unresponsive:
bdg cleanup --aggressive
bdg localhost:3000

​
No Active Session

Error: 
bdg status
# Error: No active session found
# Suggestion: Start a session with: bdg <url>
Exit Code: 83 (RESOURCE_NOT_FOUND) Solution: 
bdg localhost:3000

​
Chrome Launch Failure

Error: 
bdg localhost:3000
# Error: Chrome failed to launch
# Chrome not found in standard locations
# Tried: /usr/bin/google-chrome, /usr/bin/chromium, ...
Exit Code: 100 (CHROME_LAUNCH_FAILURE) Solutions:
Ubuntu/Debian:
sudo apt update
sudo apt install chromium-browser
macOS:
brew install --cask google-chrome
Fedora/RHEL:
sudo dnf install chromium
If Chrome is installed in non-standard location:
export CHROME_PATH=/path/to/chrome
bdg localhost:3000

bdg status --verbose
Shows detected Chrome installations and paths.

​
Port Conflict

Error: 
bdg localhost:3000
# Error: Chrome failed to launch
# Port 9222 is already in use
# Another Chrome instance may be running
Exit Code: 100 (CHROME_LAUNCH_FAILURE) Solutions: 
bdg localhost:3000 --port 9223

# Find process using port 9222
lsof -i :9222

# Kill it
kill <PID>

# Or use aggressive cleanup
bdg cleanup --aggressive

ps aux | grep chrome
# Manually kill stale Chrome processes
kill <PID>

​
Element Not Found (Stale Cache)

Error: 
bdg dom query "button"  # Returns [0], [1], [2]
# Page navigates
bdg dom click 0
# Error: Element at index 0 not accessible
# Suggestion: Re-run query to refresh cache
Exit Code: 87 (STALE_CACHE) Explanation: DOM nodeIds become invalid after navigation or DOM changes. Solution: 
# Re-run query to get fresh indices
bdg dom query "button"
# Use new index
bdg dom click 0
Prevention: Run query immediately before interaction, or use selectors directly: 
bdg dom click "button.submit"  # Uses selector, not cached index

​
CDP Timeout

Error: 
bdg dom eval "while(true) {}"
# Error: CDP operation timed out (10s)
Exit Code: 102 (CDP_TIMEOUT) Common Causes:
  • Page unresponsive
  • Infinite loop in JavaScript
  • Heavy computation
Solutions: 
bdg stop
bdg localhost:3000

bdg status --verbose
# Check if page is responsive
Break complex operations into smaller steps.

​
Permission Denied

Error: 
bdg localhost:3000
# Error: Permission denied: Cannot write to ~/.bdg/session.json
Exit Code: 82 (PERMISSION_DENIED) Solutions: 
# Check current permissions
ls -la ~/.bdg/

# Fix ownership
sudo chown -R $USER:$USER ~/.bdg/

# Fix permissions
chmod -R 755 ~/.bdg/

# Remove and recreate directory
rm -rf ~/.bdg/
bdg localhost:3000

​
Daemon Not Running

Error: 
bdg status
# Error: Cannot connect to daemon
# Suggestion: Daemon not running - it will auto-start on next session
Exit Code: 101 (CDP_CONNECTION_FAILURE) Explanation: Daemon auto-starts when needed. This error usually means daemon crashed. Solutions: 
bdg cleanup --force
bdg localhost:3000  # Daemon auto-starts

ls -la ~/.bdg/
# Look for daemon.pid, daemon.sock

# Remove if stale
rm ~/.bdg/daemon.pid ~/.bdg/daemon.sock

​
Session Files

​
Location

All session files are in ~/.bdg/: 
ls -la ~/.bdg/

drwxr-xr-x  5 user user 4096 Mar  5 21:00 .
drwxr-xr-x 30 user user 4096 Mar  5 20:50 ..
-rw-r--r--  1 user user    5 Mar  5 21:00 daemon.pid
srwxr-xr-x  1 user user    0 Mar  5 21:00 daemon.sock
-rw-r--r--  1 user user    0 Mar  5 21:00 daemon.lock
-rw-r--r--  1 user user    5 Mar  5 21:01 session.pid
-rw-r--r--  1 user user  456 Mar  5 21:01 session.meta.json
drwxr-xr-x  8 user user 4096 Mar  5 21:01 chrome-profile/

​
File Descriptions

FilePurposeWhen CreatedWhen Removed
daemon.pidDaemon process IDDaemon startDaemon exit
daemon.sockUnix socket for IPCDaemon startDaemon exit
daemon.lockAtomic lock during startupDaemon launchAfter startup
session.pidWorker process IDSession startSession stop
session.meta.jsonSession metadataSession startSession stop
session.jsonFinal telemetry outputSession stopManual removal
chrome-profile/Chrome user dataSession startSession stop

​
Inspecting Session Metadata

cat ~/.bdg/session.meta.json | jq

{
  "bdgPid": 12345,
  "chromePid": 12346,
  "startTime": "2025-03-05T21:00:00.000Z",
  "port": 9222,
  "targetId": "ABC123",
  "webSocketDebuggerUrl": "ws://localhost:9222/devtools/page/ABC123",
  "activeTelemetry": ["network", "console", "dom"]
}

​
Manual Cleanup

Manual cleanup should be a last resort. Use bdg cleanup when possible.
# Stop all bdg processes
kill $(cat ~/.bdg/daemon.pid 2>/dev/null)
kill $(cat ~/.bdg/session.pid 2>/dev/null)

# Kill Chrome
kill $(cat ~/.bdg/session.meta.json 2>/dev/null | jq -r '.chromePid')

# Remove all session files
rm -rf ~/.bdg/*

# Start fresh
bdg localhost:3000

​
Debugging Tips

​
Check Process Tree

# View all bdg processes
ps aux | grep -E "bdg|chrome" | grep -v grep

# View process tree
pstree -p $(cat ~/.bdg/daemon.pid 2>/dev/null)
Expected tree: 
node(12344) daemon.js
  └─node(12345) worker.js
      └─chrome(12346)

​
Check Port Usage

# Find what's using CDP port
lsof -i :9222

# Find all listening ports
lsof -i -P | grep LISTEN | grep chrome

​
Enable Debug Logging

# Worker logs to stderr (captured by daemon)
tail -f /tmp/worker-stderr.log  # If logging enabled

# Daemon logs
tail -f /tmp/daemon-stderr.log  # If logging enabled

​
Test IPC Connection

# Send handshake to daemon
echo '{"type":"handshake_request","sessionId":"test"}' | nc -U ~/.bdg/daemon.sock

# Expected response:
# {"type":"handshake_response","sessionId":"test","status":"ok",...}

​
Performance Issues

​
Slow Session Start

Symptoms: bdg localhost:3000 takes >10 seconds Common Causes:
  • Insufficient RAM
  • Many extensions installed
  • Large Chrome profile
Solution: Use --headless mode for faster startup:
bdg localhost:3000 --headless
  • Heavy page with many resources
  • Slow network
Solution: Use --timeout to avoid waiting:
bdg localhost:3000 --timeout 5
  • CDP port unreachable
  • Firewall blocking
Check with:
curl http://localhost:9222/json/version

​
High Memory Usage

Symptoms: Chrome process using excessive RAM Solutions: 
bdg localhost:3000 --headless
Reduces memory footprint by 30-50%.
bdg localhost:3000 --no-network --no-console
Reduces telemetry overhead.
bdg stop
Releases all memory and processes.

​
Error Messages Reference

​
Common Error Patterns

​
”Session not found”

Error: No active session found
Suggestion: Start a session with: bdg <url>
Exit Code: 83
Meaning: No worker process running Fix: Start a session

​
”Element not accessible”

Error: Element at index 0 not accessible
Suggestion: Re-run query to refresh cache
Exit Code: 87
Meaning: DOM nodeId is stale Fix: Re-run bdg dom query

​
”Worker response timeout”

Error: Worker response timeout (10s)
Exit Code: 102
Meaning: Worker didn’t respond in time Fix: Check if page is responsive, reload if needed

​
”Cannot connect to daemon”

Error: Cannot connect to daemon
Suggestion: Daemon not running - it will auto-start on next session
Exit Code: 101
Meaning: Daemon crashed or not running Fix: Use bdg cleanup --force and retry

​
Getting Help

​
Report Issues

If you encounter a bug or unexpected behavior:
  1. Collect diagnostics: 
    bdg status --verbose > diagnostics.txt
ls -la ~/.bdg/ >> diagnostics.txt
  2. Capture error output: 
    bdg your-command 2>&1 | tee error.log
  3. Report at: GitHub Issues

​
Self-Documenting Help

# Get JSON documentation for automation
bdg --help --json

# Explore CDP domains
bdg cdp --list

# Search for methods
bdg cdp --search cookie

# Describe method
bdg cdp Network.getCookies --describe

Exit Codes

Complete exit code reference

Architecture

Understanding bdg’s internals

Build docs developers (and LLMs) love

Get started for freeTalk to us