Skip to main content

​
Overview

Browser Debugger CLI uses semantic exit codes to enable reliable automation and agent-friendly error handling. Exit codes follow predictable ranges that indicate the category and severity of errors.
Exit codes are stable API - values will not change in minor versions. Safe to use in automation scripts and CI/CD pipelines.

​
Exit Code Ranges

RangeCategoryMeaningRetry Strategy
0SuccessCommand completed successfully-
1Generic FailureLegacy/backward compatibilityAvoid in new code
80-99User ErrorsInvalid input, permissions, missing resourcesFix input and retry
100-119Software ErrorsBugs, timeouts, integration failuresInvestigate or report

​
Philosophy

​
User Errors (80-99)

Problems caused by incorrect usage, invalid input, or environmental constraints. The user can fix these by adjusting their command or environment. Examples:
  • Invalid URL format
  • File not found
  • Insufficient permissions
  • Resource already exists
Action: Provide clear error message with suggestion for fix.

​
Software Errors (100-119)

Problems caused by bugs, external service failures, or unexpected conditions. Requires investigation by developers or may resolve with retry. Examples:
  • Chrome launch failure
  • CDP connection timeout
  • Unhandled exception
  • Session file corruption
Action: Include diagnostics and suggest reporting the issue.

​
Complete Reference

​
Success

​
0
SUCCESS
Operation completed successfullyExample:
bdg localhost:3000
echo $?  # 0

​
Generic Failure

​
1
GENERIC_FAILURE
Generic failure (backward compatibility)Note: Use specific codes (80-119) in new code. This exists for backward compatibility.Example:
bdg some-invalid-command
echo $?  # 1

​
User Errors (80-99)

​
80
INVALID_URL
Invalid URL format or unreachable URLExample:
bdg not-a-valid-url
# Error: Invalid URL: not-a-valid-url
# Suggestion: Use format: http://localhost:3000 or localhost:3000
echo $?  # 80
​
81
INVALID_ARGUMENTS
Invalid command-line arguments or optionsExample:
bdg dom query --invalid-flag
# Error: Unknown option: --invalid-flag
echo $?  # 81
Common Cases:
  • Unknown flags
  • Invalid flag values
  • Missing required arguments
  • Type mismatches (e.g., string where number expected)
​
82
PERMISSION_DENIED
Insufficient permissions for operationExample:
bdg localhost:3000  # When ~/.bdg/ is not writable
# Error: Permission denied: Cannot write to ~/.bdg/session.json
echo $?  # 82
​
83
RESOURCE_NOT_FOUND
Requested resource not found (session, file, element, etc.)Example:
bdg status  # When no session is running
# Error: No active session found
# Suggestion: Start a session with: bdg <url>
echo $?  # 83
Common Cases:
  • No active session
  • Element not found (DOM query)
  • Network request ID not found
  • File does not exist
​
84
RESOURCE_ALREADY_EXISTS
Resource already exists (duplicate session, etc.)Example:
bdg localhost:3000  # When session is already running
# Error: Session already running (PID: 12345)
# Suggestion: Stop current session with: bdg stop
echo $?  # 84
​
85
RESOURCE_BUSY
Resource is locked or busyExample:
bdg cleanup  # When session is still active
# Error: Session still active (PID: 12345)
# Suggestion: Stop gracefully: bdg stop
#            Force cleanup: bdg cleanup --force
echo $?  # 85
​
86
DAEMON_ALREADY_RUNNING
Daemon is already runningExample:
# Internal check - prevents duplicate daemons
echo $?  # 86
Note: Rarely seen by users - handled internally during daemon startup.
​
87
STALE_CACHE
Cache invalidated by navigation or DOM changesExample:
bdg dom query "button"  # Returns indices [0], [1], [2]
# Page navigates or DOM changes
bdg dom click 0  # Element at index 0 no longer valid
# Error: Element at index 0 not accessible
# Suggestion: Re-run query to refresh cache
echo $?  # 87
Important: This is distinct from RESOURCE_NOT_FOUND (83) - it indicates the element existed but is now stale due to DOM changes.
​
88
NO_FORMS_FOUND
No forms discovered on the pageExample:
bdg dom form
# Error: No forms found on current page
# Suggestion: Verify page has loaded completely
echo $?  # 88
​
89
FORM_IN_IFRAME
Form is inside an iframe (cross-origin or same-origin)Example:
bdg dom form
# Error: Form detected in iframe - bdg cannot access iframe content
# Suggestion: Navigate directly to iframe URL if accessible
echo $?  # 89

​
Software Errors (100-119)

​
100
CHROME_LAUNCH_FAILURE
Chrome browser failed to launchExample:
bdg localhost:3000
# Error: Chrome failed to launch
# Chrome not found in standard locations
# Tried: /usr/bin/google-chrome, /usr/bin/chromium, ...
echo $?  # 100
Common Causes:
  • Chrome not installed
  • Port conflict (9222 already in use)
  • Missing dependencies (Linux)
  • Insufficient resources
​
101
CDP_CONNECTION_FAILURE
Failed to connect to Chrome DevTools ProtocolExample:
bdg localhost:3000
# Error: Failed to connect to CDP WebSocket
# Connection refused: ws://localhost:9222/devtools/page/...
echo $?  # 101
Common Causes:
  • Chrome crashed after launch
  • WebSocket endpoint unreachable
  • Network/firewall issues
​
102
CDP_TIMEOUT
CDP operation timed outExample:
bdg dom eval "while(true) {}"
# Error: CDP operation timed out (10s)
echo $?  # 102
Common Causes:
  • Page unresponsive
  • Infinite loop in JavaScript
  • Network latency
  • Heavy computation blocking event loop
​
103
SESSION_FILE_ERROR
Session file read/write errorExample:
bdg stop
# Error: Failed to write session.json
# ENOSPC: no space left on device
echo $?  # 103
Common Causes:
  • Disk full
  • File system corruption
  • Permission changes during session
​
104
UNHANDLED_EXCEPTION
Unhandled exception in codeExample:
bdg some-command
# Error: Unhandled exception: TypeError: Cannot read property 'x' of undefined
echo $?  # 104
Note: This indicates a bug. Please report with full error message.
​
105
SIGNAL_HANDLER_ERROR
Signal handler errorExample:
# Internal error during SIGTERM/SIGINT handling
echo $?  # 105
Note: Rare - indicates cleanup failure during shutdown.
​
110
SOFTWARE_ERROR
Generic software error (use specific codes when possible)Example:
bdg some-command
# Error: Unexpected internal error
echo $?  # 110
Note: Use more specific codes (100-109) when possible.

​
Usage in Automation

​
Shell Scripts

#!/bin/bash
set -e  # Exit on error

bdg localhost:3000
START_CODE=$?

if [ $START_CODE -eq 0 ]; then
  echo "Session started successfully"
elif [ $START_CODE -ge 80 ] && [ $START_CODE -le 99 ]; then
  echo "User error - check your input"
  exit 1
elif [ $START_CODE -ge 100 ] && [ $START_CODE -le 119 ]; then
  echo "Software error - may need investigation"
  exit 2
else
  echo "Unexpected exit code: $START_CODE"
  exit 3
fi

​
Python

import subprocess
import sys

result = subprocess.run(['bdg', 'localhost:3000'])

if result.returncode == 0:
    print("Success")
elif 80 <= result.returncode <= 99:
    print("User error - check input")
    sys.exit(1)
elif 100 <= result.returncode <= 119:
    print("Software error - investigate")
    sys.exit(2)
else:
    print(f"Unexpected exit code: {result.returncode}")
    sys.exit(3)

​
CI/CD (GitHub Actions)

name: Test with bdg
on: [push]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - name: Start bdg session
        id: bdg
        run: |
          bdg http://localhost:3000 --headless
          echo "exit_code=$?" >> $GITHUB_OUTPUT
        continue-on-error: true
      
      - name: Check result
        run: |
          CODE=${{ steps.bdg.outputs.exit_code }}
          if [ $CODE -eq 0 ]; then
            echo "✅ Session started"
          elif [ $CODE -ge 80 ] && [ $CODE -le 99 ]; then
            echo "❌ User error (exit $CODE)"
            exit 1
          elif [ $CODE -ge 100 ] && [ $CODE -le 119 ]; then
            echo "❌ Software error (exit $CODE)"
            exit 2
          fi

​
JSON Output

When using --json flag, exit codes are included in error responses: 
bdg status --json

{
  "version": "0.5.1",
  "success": false,
  "error": "No active session found",
  "exitCode": 83,
  "suggestion": "Start a session with: bdg <url>"
}
Access via jq: 
RESPONSE=$(bdg status --json)
EXIT_CODE=$(echo $RESPONSE | jq '.exitCode')

if [ $EXIT_CODE -eq 83 ]; then
  echo "No session - starting one"
  bdg localhost:3000
fi

​
Discovering Exit Codes

Use bdg --help --json to get machine-readable documentation including all exit codes: 
bdg --help --json | jq '.exitCodes'

[
  {"code": 0, "name": "SUCCESS", "description": "Operation completed successfully"},
  {"code": 1, "name": "GENERIC_FAILURE", "description": "Generic failure"},
  {"code": 80, "name": "INVALID_URL", "description": "Invalid URL format"},
  {"code": 81, "name": "INVALID_ARGUMENTS", "description": "Invalid arguments"},
  ...
]

​
Stability Guarantees

Exit codes are stable public API

​
Versioning Policy

  • ✅ Exit code values will not change in minor versions
  • ✅ New exit codes may be added in minor versions (within ranges)
  • ✅ Exit code semantics (meaning) remain consistent
  • ⚠️ Existing codes only removed in major versions with deprecation notice

​
Migration Policy

  • Deprecated codes documented in CHANGELOG.md
  • Deprecated codes functional for at least one major version
  • Clear migration path provided

​
Source Code

Definition: src/utils/exitCodes.ts 
export const EXIT_CODES = {
  SUCCESS: 0,
  GENERIC_FAILURE: 1,
  INVALID_URL: 80,
  INVALID_ARGUMENTS: 81,
  PERMISSION_DENIED: 82,
  RESOURCE_NOT_FOUND: 83,
  RESOURCE_ALREADY_EXISTS: 84,
  RESOURCE_BUSY: 85,
  DAEMON_ALREADY_RUNNING: 86,
  STALE_CACHE: 87,
  NO_FORMS_FOUND: 88,
  FORM_IN_IFRAME: 89,
  CHROME_LAUNCH_FAILURE: 100,
  CDP_CONNECTION_FAILURE: 101,
  CDP_TIMEOUT: 102,
  SESSION_FILE_ERROR: 103,
  UNHANDLED_EXCEPTION: 104,
  SIGNAL_HANDLER_ERROR: 105,
  SOFTWARE_ERROR: 110,
} as const;

Architecture

Understanding bdg’s process model

Troubleshooting

Common errors and diagnostic commands

Build docs developers (and LLMs) love

Get started for freeTalk to us