# Domain-Specific Error Types ## Domain-Specific Errors These concrete error types provide semantic meaning for common failure scenarios across the library ecosystem. Each error type has sensible defaults for severity and retry behavior, but these can be overridden when needed. ## ValidationError For data validation failures, schema validation, and constraint violations. ------------------------------------------------------------------------ ### ValidationError ``` python def ValidationError( message:str, # User-friendly error message debug_info:Optional=None, # Optional developer details context:Optional=None, # Structured error context severity:ErrorSeverity=, # Error severity level is_retryable:bool=False, # Validation errors typically need fixes, not retries cause:Optional=None, # Original exception if chaining validation_errors:Optional=None, # Structured validation details ): ``` *Raised when validation fails.* ### Example: ValidationError ``` python # Schema validation failure error1 = ValidationError( message="Plugin configuration is invalid", debug_info="Field 'model_id' is required but missing", context=ErrorContext(plugin_id="whisper_large", operation="validate_config"), validation_errors={ "model_id": "required field missing", "temperature": "must be between 0.0 and 1.0" } ) print("Validation Error:", error1.get_user_message()) print("Details:", error1.validation_errors) ``` Validation Error: Plugin configuration is invalid Details: {'model_id': 'required field missing', 'temperature': 'must be between 0.0 and 1.0'} ``` python # Resource validation failure error2 = ValidationError( message="GPU unavailable for job execution", debug_info="GPU 0 in use by external process (PID 12345)", context=ErrorContext( job_id="job-123", plugin_id="whisper_large", operation="validate_resources", extra={"gpu_id": 0, "required_memory_mb": 8192} ) ) print("\nResource Validation:", error2.get_user_message()) print("Debug:", error2.get_debug_message()) ``` Resource Validation: GPU unavailable for job execution Debug: GPU unavailable for job execution | Debug: GPU 0 in use by external process (PID 12345) ## ConfigurationError For configuration file issues, missing settings, and config loading/saving failures. ------------------------------------------------------------------------ ### ConfigurationError ``` python def ConfigurationError( message:str, # User-friendly error message debug_info:Optional=None, # Optional developer details context:Optional=None, # Structured error context severity:ErrorSeverity=, # Error severity level is_retryable:bool=False, # Config issues usually need manual fixes cause:Optional=None, # Original exception if chaining config_path:Optional=None, # Path to problematic config file ): ``` *Raised when configuration operations fail.* ### Example: ConfigurationError ``` python # Config file not found error3 = ConfigurationError( message="Configuration file not found", debug_info="Expected config at /home/user/.config/app/settings.json", context=ErrorContext(operation="load_config"), config_path="/home/user/.config/app/settings.json" ) print("Config Error:", error3.get_user_message()) print("Path:", error3.config_path) ``` Config Error: Configuration file not found Path: /home/user/.config/app/settings.json ``` python # Config parse error with chaining import json try: json.loads('{"broken": json}') except json.JSONDecodeError as e: error4 = ConfigurationError( message="Failed to parse configuration file", debug_info="JSON syntax error in config file", context=ErrorContext(plugin_id="whisper_base", operation="load_plugin_config"), config_path="configs/whisper_base.json", cause=e ) print("\nConfig Parse Error:", error4.get_user_message()) print("Debug:", error4.get_debug_message()) ``` Config Parse Error: Failed to parse configuration file Debug: Failed to parse configuration file | Debug: JSON syntax error in config file | Caused by: JSONDecodeError: Expecting value: line 1 column 12 (char 11) ## ResourceError For resource conflicts and availability issues (GPU busy, insufficient memory, etc.). ------------------------------------------------------------------------ ### ResourceError ``` python def ResourceError( message:str, # User-friendly error message debug_info:Optional=None, # Optional developer details context:Optional=None, # Structured error context severity:ErrorSeverity=, # Often transient is_retryable:bool=True, # Resource conflicts may be temporary cause:Optional=None, # Original exception if chaining resource_type:Optional=None, # "GPU", "Memory", "Disk", etc. suggested_action:Optional=None, # Guidance for resolution ): ``` *Raised when resource conflicts or unavailability prevent operation.* ### Example: ResourceError ``` python # GPU conflict error5 = ResourceError( message="GPU currently unavailable", debug_info="GPU 0 in use by transcription worker (PID 54321)", context=ErrorContext( job_id="job-456", operation="start_job", extra={"gpu_id": 0, "conflicting_worker_pid": 54321} ), resource_type="GPU", suggested_action="Wait for current job to complete or cancel it", is_retryable=True ) print("Resource Error:", error5.get_user_message()) print("Resource type:", error5.resource_type) print("Suggested action:", error5.suggested_action) print("Retryable:", error5.is_retryable) ``` Resource Error: GPU currently unavailable Resource type: GPU Suggested action: Wait for current job to complete or cancel it Retryable: True ``` python # Memory error error6 = ResourceError( message="Insufficient memory to load model", debug_info="Required: 8GB, Available: 2GB", context=ErrorContext( plugin_id="whisper_large", operation="load_model", extra={"required_gb": 8, "available_gb": 2} ), severity=ErrorSeverity.ERROR, resource_type="Memory", suggested_action="Use a smaller model or free up system memory", is_retryable=False # Won't fix itself ) print("\nMemory Error:", error6.get_user_message()) print("Suggested action:", error6.suggested_action) ``` Memory Error: Insufficient memory to load model Suggested action: Use a smaller model or free up system memory ## PluginError For plugin discovery, loading, initialization, and execution failures. ------------------------------------------------------------------------ ### PluginError ``` python def PluginError( message:str, # User-friendly error message debug_info:Optional=None, # Optional developer details context:Optional=None, # Structured error context severity:ErrorSeverity=, # Error severity level is_retryable:bool=False, # Plugin errors usually need fixes cause:Optional=None, # Original exception if chaining plugin_id:Optional=None, # ID of problematic plugin plugin_name:Optional=None, # Name of problematic plugin ): ``` *Raised when plugin operations fail.* ### Example: PluginError ``` python # Plugin not found error7 = PluginError( message="Plugin not found", debug_info="No plugin registered with ID 'transcription_whisper_huge'", context=ErrorContext(operation="load_plugin"), plugin_id="transcription_whisper_huge" ) print("Plugin Error:", error7.get_user_message()) print("Plugin ID:", error7.plugin_id) ``` Plugin Error: Plugin not found Plugin ID: transcription_whisper_huge ``` python # Plugin initialization failure with cause try: raise ImportError("No module named 'torch'") except ImportError as e: error8 = PluginError( message="Failed to initialize plugin", debug_info="Missing required dependency: torch", context=ErrorContext( plugin_id="whisper_large", operation="initialize" ), plugin_id="whisper_large", plugin_name="Whisper Large", cause=e ) print("\nPlugin Init Error:", error8.get_user_message()) print("Plugin name:", error8.plugin_name) print("Debug:", error8.get_debug_message()) ``` Plugin Init Error: Failed to initialize plugin Plugin name: Whisper Large Debug: Failed to initialize plugin | Debug: Missing required dependency: torch | Caused by: ImportError: No module named 'torch' ## WorkerError For worker process failures, communication errors, and job execution issues. ------------------------------------------------------------------------ ### WorkerError ``` python def WorkerError( message:str, # User-friendly error message debug_info:Optional=None, # Optional developer details context:Optional=None, # Structured error context severity:ErrorSeverity=, # Error severity level is_retryable:bool=True, # Worker errors may be transient cause:Optional=None, # Original exception if chaining worker_type:Optional=None, # "transcription", "llm", etc. job_id:Optional=None, # Job that failed ): ``` *Raised when worker process operations fail.* ### Example: WorkerError ``` python # Worker crash error9 = WorkerError( message="Worker process terminated unexpectedly", debug_info="Worker PID 98765 exited with code -11 (SIGSEGV)", context=ErrorContext( job_id="job-789", worker_pid=98765, operation="execute_job" ), severity=ErrorSeverity.CRITICAL, worker_type="transcription", job_id="job-789", is_retryable=True # Worker can be restarted ) print("Worker Error:", error9.get_user_message()) print("Worker type:", error9.worker_type) print("Job ID:", error9.job_id) print("Retryable:", error9.is_retryable) ``` Worker Error: Worker process terminated unexpectedly Worker type: transcription Job ID: job-789 Retryable: True ``` python # Worker timeout error10 = WorkerError( message="Worker operation timed out", debug_info="No response from worker after 30 seconds", context=ErrorContext( worker_pid=11111, operation="reload_plugin", extra={"timeout_seconds": 30} ), severity=ErrorSeverity.WARNING, worker_type="transcription", is_retryable=True ) print("\nWorker Timeout:", error10.get_user_message()) print("Debug:", error10.get_debug_message()) ``` Worker Timeout: Worker operation timed out Debug: Worker operation timed out | Debug: No response from worker after 30 seconds ## Summary: When to Use Each Error Type
Error Type Use When Default Retryable Example
ValidationError Data/schema validation fails No Plugin config invalid, GPU requirements not met
ConfigurationError Config file issues No Config file not found, parse error
ResourceError Resource conflicts/unavailable Yes GPU busy, out of memory
PluginError Plugin operations fail No Plugin not found, init failed
WorkerError Worker process issues Yes Worker crashed, communication timeout
All inherit from `BaseError`, so you can catch them generically or specifically as needed. ## Example: Catching Multiple Error Types ``` python def handle_errors(): """Demonstrate catching different error types.""" scenarios = [ ValidationError("Config invalid", context=ErrorContext(operation="validate")), ResourceError("GPU busy", resource_type="GPU", is_retryable=True), WorkerError("Worker crashed", worker_type="transcription") ] for error in scenarios: try: raise error except ValidationError as e: print(f"Validation failed: {e.get_user_message()}") print(f" → Action: Fix the input and try again\n") except ResourceError as e: print(f"Resource issue: {e.get_user_message()}") if e.is_retryable: print(f" → Action: Retry after {e.resource_type} becomes available\n") except WorkerError as e: print(f"Worker issue: {e.get_user_message()}") print(f" → Action: Restart {e.worker_type} worker\n") except BaseError as e: # Catch-all for any other error types print(f"Unexpected error: {e.get_user_message()}\n") handle_errors() ``` Validation failed: Config invalid → Action: Fix the input and try again Resource issue: GPU busy → Action: Retry after GPU becomes available Worker issue: Worker crashed → Action: Restart transcription worker