title: “Error Taxonomy & Structured Error Handling” version: 1.1.1 date: 2026-01-23

Error Taxonomy & Structured Error Handling

Comprehensive error taxonomy, codes, user messages, and structured error handling for BranchPy CLI, engines, dashboard, and server components.

Version: 1.1.1
Last Updated: January 23, 2026

Table of Contents

1. Overview
2. Error Code Format
3. Error Taxonomy
4. CLI Error Codes
5. Server Error Codes
6. Exception Hierarchy
7. Error Messages
8. Structured Error Class
9. Error Handling Patterns
10. Exit Codes
11. Best Practices
12. Cross-References

Overview

BranchPy uses a structured error system to handle, report, and communicate issues across its CLI, engines, dashboard, and server components. Errors are defined with stable codes, user-friendly messages, and support for context and diagnostics, ensuring robust and user-friendly error management.

Key Features

• Stable, extend-only error codes for common failure scenarios
• User-friendly error messages for CLI, dashboard, and logs
• Structured error class with context and diagnostics support
• Support for detailed error reporting and troubleshooting
• Cross-platform compatibility with Python 3 and TypeScript
• Consistent error format across CLI, server, and VS Code extension

Error Code Format

CLI Error Codes (E_-prefixed)

Pattern: E_<CATEGORY>_<SPECIFIC>

• E_: Error prefix
• CATEGORY: Component or subsystem (e.g., LIC, NET, PARSE, AUTH)
• SPECIFIC: Descriptive identifier (e.g., INVALID, FAIL, MISSING)

Examples:

• E_LIC_INVALID - License validation failed
• E_NET_FAIL - Network error while contacting remote service
• E_PARSE_SYNTAX - Syntax error during file parsing

Server Error Codes (BPY-prefixed)

Pattern: BPY-XXXX

• BPY: BranchPy namespace
• XXXX: 4-digit code (category range + specific error)

Example Categories:

• 1000–1099 - Validation Errors
• 1100–1199 - Resource Not Found
• 1200–1299 - PILOT Module Errors
• 1300–1399 - Schema Errors
• 2000–2999 - Internal Server Errors

Examples:

• BPY-1001 - Missing required parameter
• BPY-1201 - Path not found in stats2
• BPY-2001 - Database connection failed

Error Taxonomy

CLI Error Categories

Server Error Categories

CLI Error Codes

Licensing Errors

Binary Management Errors

Network Errors

Permission Errors

Update Errors

Configuration Errors

Server Error Codes

Validation Errors (1000–1099)

Resource Not Found (1100–1199)

PILOT Module Errors (1200–1299)

Schema Errors (1300–1399)

Internal Server Errors (2000–2999)

Exception Hierarchy

All BranchPy exceptions inherit from BranchPyError:

BranchPyError (base exception)
├── ParseError
│   ├── SyntaxError
│   ├── InvalidPythonCodeError
│   └── MalformedASTError
├── ValidationError
│   ├── ConfigValidationError
│   ├── SchemaValidationError
│   └── DataValidationError
├── ConfigError
│   ├── ConfigNotFoundError
│   ├── InvalidConfigError
│   └── ConfigMigrationError
├── AuthenticationError
│   ├── InvalidCredentialsError
│   ├── TokenExpiredError
│   └── TokenInvalidError
├── AuthorizationError
│   ├── FeatureNotEntitledError
│   ├── PlanLimitExceededError
│   └── DeviceLimitExceededError
├── NetworkError
│   ├── ConnectionError
│   ├── TimeoutError
│   └── APIError
├── FileSystemError
│   ├── FileNotFoundError
│   ├── PermissionError
│   └── DiskFullError
├── AnalysisError
│   ├── CrossFileTrackingError
│   ├── PropagationError
│   └── CFGBuildError
├── AIError
│   ├── ProviderError
│   ├── ModelNotAvailableError
│   └── SafetyViolationError
└── QuickFixError
    ├── TransformationError
    ├── UnsafeOperationError
    └── InvalidExpressionError

Error Messages

ERROR_MESSAGES Dictionary

User-friendly error messages mapped to error codes:

ERROR_MESSAGES = {
    E_LIC_INVALID: "Your license couldn't be validated.",
    E_LIC_OFFLINE: "License server unreachable (grace period may apply).",
    E_BIN_MISSING: "Expected runtime binary not found.",
    E_SIG_FAIL: "Downloaded file failed integrity verification.",
    E_NET_FAIL: "Network error while contacting a remote service.",
    E_PERM_DENIED: "Insufficient permissions to complete the operation.",
    E_UPDATE_BUSY: "Update is already in progress.",
    E_UPDATE_ROLLBACK: "The new binary failed to start; rolled back to previous version.",
    E_CFG_CORRUPT: "Configuration or state file is malformed.",
}

Structured Error Class

BranchPyError

Base class for all BranchPy exceptions with structured fields for context and diagnostics.

@dataclass
class BranchPyError(Exception):
    code: str                      # Error code (e.g., E_LIC_INVALID)
    detail: Optional[str] = None   # Additional detail message
    context: Optional[dict] = None # Context dictionary (url, file_path, etc.)

    def __str__(self) -> str:
        base = ERROR_MESSAGES.get(self.code, self.code)
        if self.detail:
            base += f" Detail: {self.detail}"
        return base

    def to_user_block(self, version: str, platform: str, log_path: str) -> str:
        """Generate support-ready error report block."""
        lines = [
            ERROR_MESSAGES.get(self.code, self.code),
            "",
            "Copy this block if you need support:",
            f"CODE: {self.code}",
            f"VERSION: {version}",
            f"PLATFORM: {platform}",
            f"LOG: {log_path}",
        ]
        if self.context:
            for k, v in self.context.items():
                lines.append(f"{k.upper()}: {v}")
        return "\n".join(lines)

Usage Example

# Raising an error with context
raise BranchPyError(
    E_NET_FAIL,
    detail="Timeout contacting server",
    context={"url": "https://api.branchpy.com"}
)

# Generating support block
try:
    # ... operation ...
except BranchPyError as e:
    print(e.to_user_block(
        version="1.1.1",
        platform="Windows",
        log_path="C:\\Users\\user\\.branchpy\\logs\\error.log"
    ))

Server Error Payload (JSON)

{
  "error": true,
  "code": "BPY-1201",
  "message": "Path p999 not found in project myGame",
  "severity": "warn",
  "suggestion": "Check available paths using /paths endpoint",
  "correlation_id": "abc123",
  "context": {
    "project_name": "myGame",
    "requested_path": "p999",
    "available_paths": ["p001", "p002", "p003"]
  }
}

Error Handling Patterns

Typical Workflow

1. Raise BranchPyError with appropriate code, detail, and context
2. Map error codes to user-friendly messages for display
3. Use to_user_block for generating support-ready error reports
4. Validate error handling logic with test scripts and example usage

CLI Error Handling

import sys
from branchpy.errors import BranchPyError, ParseError, AuthenticationError

try:
    main()
    sys.exit(0)  # Success
except ParseError:
    sys.exit(2)
except AuthenticationError:
    sys.exit(5)
except BranchPyError as e:
    logger.error(f"{e.code}: {e}")
    sys.exit(1)
except Exception as e:
    logger.exception("Unexpected error")
    sys.exit(1)

Server Error Response

interface ErrorResponse {
  error: true;
  code: string;                     // e.g., "BPY-1201"
  message: string;                  // Human-readable error
  severity: 'info' | 'warn' | 'error';
  suggestion?: string;              // Optional fix guidance
  correlation_id?: string;          // Request tracking ID
}

Retry & Backoff (Server Errors)

async function fetchWithRetry(url: string, maxAttempts = 3): Promise<Response> {
  for (let attempt = 1; attempt <= maxAttempts; attempt++) {
    try {
      const response = await fetch(url);
      if (response.ok || response.status < 500) {
        return response; // Success or client error (no retry)
      }
      // 5xx error → retry
    } catch (error) {
      // Network error → retry
    }
    
    if (attempt < maxAttempts) {
      const delayMs = Math.min(1000 * Math.pow(2, attempt - 1), 8000);
      await new Promise(resolve => setTimeout(resolve, delayMs));
    }
  }
  throw new Error(`Failed after ${maxAttempts} attempts`);
}

Delays:

• Attempt 1 → immediate
• Attempt 2 → 1s delay
• Attempt 3 → 2s delay
• Maximum delay → 8s

Exit Codes

Exit codes for CLI commands and scripts:

# Exit codes
EXIT_SUCCESS = 0              # Success, no issues
EXIT_ERROR = 1                # General error
EXIT_PARSE_ERROR = 2          # Parsing failed
EXIT_VALIDATION_ERROR = 3     # Validation failed
EXIT_CONFIG_ERROR = 4         # Configuration error
EXIT_AUTH_ERROR = 5           # Authentication failed
EXIT_AUTHZ_ERROR = 6          # Authorization failed
EXIT_NET_ERROR = 7            # Network error
EXIT_FS_ERROR = 8             # File system error
EXIT_ANALYSIS_ERROR = 9       # Analysis error
EXIT_AI_ERROR = 10            # AI provider error
EXIT_QUICKFIX_ERROR = 11      # QuickFix transformation error

Exit Code Mapping

Best Practices

1. Use Stable Error Codes

• Error codes are extend-only for backward compatibility
• Add new codes for emerging failure scenarios
• Never change existing error code meanings

2. Provide Detailed Context

# Good
raise BranchPyError(
    E_NET_FAIL,
    detail="Timeout contacting server after 30s",
    context={
        "url": "https://api.branchpy.com",
        "timeout_seconds": 30,
        "retry_count": 3
    }
)

# Avoid
raise BranchPyError(E_NET_FAIL)

3. Use to_user_block for Support

try:
    # ... operation ...
except BranchPyError as e:
    support_block = e.to_user_block(
        version=VERSION,
        platform=platform.system(),
        log_path=log_file_path
    )
    print(support_block)

4. Log Before Raising

logger.error(
    "License validation failed",
    extra={
        "license_key": license_key[:8] + "...",
        "validation_url": validation_url,
        "error": error_msg
    }
)
raise BranchPyError(E_LIC_INVALID, detail=error_msg)

5. Handle Errors Gracefully

# Provide helpful error messages
try:
    require_feature("ai_review")
except FeatureNotEntitledError as e:
    print(f"⚠️  AI Review requires Pro plan")
    print(f"Your current plan: {e.details['current_plan']}")
    print(f"Upgrade at: https://branchpy.com/upgrade")

6. Test Error Handling

import pytest
from branchpy.errors import BranchPyError, E_LIC_INVALID

def test_license_error_handling():
    with pytest.raises(BranchPyError) as exc_info:
        validate_license("invalid-key")
    
    assert exc_info.value.code == E_LIC_INVALID
    assert "context" in exc_info.value.__dict__

Performance Considerations

• Optimized for efficient error reporting and diagnostics
• Minimal overhead for exception creation and handling
• Structured context avoids string concatenation overhead
• Support-ready blocks generated on-demand

Error Handling & Edge Cases

• Handles missing codes: Falls back to error code string
• Handles malformed messages: Provides generic message
• Handles context errors: Validates context dictionary
• Provides detailed error messages and logging for debugging

Extending & Customization

Adding New Error Codes

1. Add error code constant to branchpy/errors.py:

   E_NEW_ERROR = "E_NEW_ERROR"

2. Add user-friendly message to ERROR_MESSAGES:

   ERROR_MESSAGES = {
       # ... existing codes ...
       E_NEW_ERROR: "User-friendly message for new error.",
   }

3. Document in error taxonomy (this file)

Extending BranchPyError Class

@dataclass
class EnhancedBranchPyError(BranchPyError):
    """Extended error class with additional diagnostics."""
    timestamp: Optional[str] = None
    stack_trace: Optional[str] = None
    
    def to_detailed_report(self) -> str:
        """Generate detailed diagnostic report."""
        report = self.to_user_block(VERSION, platform.system(), log_path)
        if self.timestamp:
            report += f"\nTIMESTAMP: {self.timestamp}"
        if self.stack_trace:
            report += f"\nSTACK TRACE:\n{self.stack_trace}"
        return report

Integration

Error system works with:

• CLI - Command-line interface error handling
• Engines - Analysis engine error reporting
• Dashboard - Web dashboard error display
• Core modules - Central error management
• Server - REST API error responses
• VS Code Extension - Extension error mapping and display

Supported Environments

• Python 3.8+ for CLI and engines
• TypeScript/Node.js for server and VS Code extension
• Cross-platform (Windows, macOS, Linux)

Cross-References

Related Documentation

• API Error Codes & Handling - Exception hierarchy and API error handling
• API Contracts - Request/response formats and error handling
• API README - API overview
• Server Protocol - Server error codes and responses
• Server Architecture - Server error handling
• Backend Architecture - Backend error handling
• Logging - Error logging configuration

Source References:

• Original Error Documentation: docs/v1.1.0/Errors/BranchPy_Errors_Documentation.md
• API Error Documentation: docs/v1.1.0/API/errors.md
• Error Implementation: BranchPyApp/branchpy/errors.py
• Error Constants: BranchPyApp/branchpy/contract.py
• Server Protocol: docs/v1.1.0/Server/PROTOCOL.md
• Version: 1.1.1
• Last Updated: January 23, 2026