Exception Reference

Complete catalog of framework exceptions with inheritance structure and usage patterns.

The framework implements a comprehensive exception hierarchy that provides precise error classification for all failure modes. The exceptions are designed to support intelligent retry logic, user-friendly error reporting, and comprehensive debugging information.

Base Framework Exceptions

FrameworkError

class osprey.base.errors.FrameworkError

Bases: Exception

Base exception for all framework-related errors.

This is the root exception class for all custom exceptions within the Osprey Framework. It provides a common base for framework-specific error handling and categorization.

Base exception for all framework-related errors. Root exception class for all custom exceptions within the Osprey Framework.

RegistryError

class osprey.base.errors.RegistryError

Bases: FrameworkError

Exception for registry-related errors.

Raised when issues occur with component registration, lookup, or management within the framework’s registry system.

Exception for registry-related errors. Raised when issues occur with component registration, lookup, or management within the framework’s registry system.

ConfigurationError

class osprey.base.errors.ConfigurationError

Bases: FrameworkError

Exception for configuration-related errors.

Raised when configuration files are invalid, missing required settings, or contain incompatible values that prevent proper system operation.

Exception for configuration-related errors. Raised when configuration files are invalid, missing required settings, or contain incompatible values.

Python Executor Service Exceptions

ErrorCategory

class osprey.services.python_executor.exceptions.ErrorCategory(value)

Bases: Enum

High-level error categories that determine appropriate recovery strategies.

This enumeration classifies all Python executor errors into categories that directly correspond to different recovery and retry strategies. The categorization enables intelligent error handling that can automatically determine whether to retry execution, regenerate code, or require user intervention.

Variables:

• INFRASTRUCTURE – Container connectivity, network, or external service issues

• CODE_RELATED – Syntax errors, runtime failures, or logical issues in generated code

• WORKFLOW – Service workflow control issues like timeouts or retry limits

• CONFIGURATION – Invalid or missing configuration settings

Note

Error categories are used by the service’s retry logic to determine the appropriate recovery strategy without requiring explicit error type checking.

See also

PythonExecutorException : Base exception class using these categories PythonExecutorException.should_retry_execution() : Infrastructure retry logic PythonExecutorException.should_retry_code_generation() : Code regeneration logic

High-level error categories that determine appropriate recovery strategies.

Categories

INFRASTRUCTURE
CODE_RELATED
WORKFLOW
CONFIGURATION

INFRASTRUCTURE = 'infrastructure'

CODE_RELATED = 'code_related'

WORKFLOW = 'workflow'

CONFIGURATION = 'configuration'

PythonExecutorException

class osprey.services.python_executor.exceptions.PythonExecutorException(message, category, technical_details=None, folder_path=None)

Bases: Exception

Base exception class for all Python executor service operations.

This abstract base class provides common functionality for all Python executor exceptions, including error categorization, context management, and retry logic determination. It serves as the foundation for the entire exception hierarchy and enables consistent error handling across the service.

The class implements a category-based approach to error handling that allows the service to automatically determine appropriate recovery strategies without requiring explicit exception type checking in the retry logic.

Parameters:

• message (str) – Human-readable error description

• category (ErrorCategory) – Error category that determines recovery strategy

• technical_details (Dict[str, Any], optional) – Additional technical information for debugging

• folder_path (Path, optional) – Path to execution folder if available for debugging

Note

This base class should not be raised directly. Use specific exception subclasses that provide more detailed error information.

See also

ErrorCategory : Error categorization for recovery strategies ContainerConnectivityError : Infrastructure error example CodeRuntimeError : Code-related error example

Base exception class for all Python executor service operations.

Key Methods

is_infrastructure_error	Check if this is an infrastructure or connectivity error.
is_code_error	Check if this is a code-related error requiring code regeneration.
is_workflow_error	Check if this is a workflow control error requiring special handling.
should_retry_execution	Determine if the same code execution should be retried.
should_retry_code_generation	Determine if code should be regenerated and execution retried.

__init__(message, category, technical_details=None, folder_path=None)

is_infrastructure_error()

Check if this is an infrastructure or connectivity error.

Infrastructure errors indicate problems with external dependencies like container connectivity, network issues, or service availability. These errors typically warrant retrying the same operation after a delay.

Returns:

True if this is an infrastructure error

Return type:

bool

Examples

Checking error type for retry logic:

>>> try:
...     await execute_code(code)
... except PythonExecutorException as e:
...     if e.is_infrastructure_error():
...         await asyncio.sleep(1)  # Brief delay
...         await execute_code(code)  # Retry same code

is_code_error()

Check if this is a code-related error requiring code regeneration.

Code errors indicate problems with the generated or provided Python code, including syntax errors, runtime failures, or logical issues. These errors typically require regenerating the code with error feedback.

Returns:

True if this is a code-related error

Return type:

bool

Examples

Handling code errors with regeneration:

>>> try:
...     await execute_code(code)
... except PythonExecutorException as e:
...     if e.is_code_error():
...         new_code = await regenerate_code(error_feedback=str(e))
...         await execute_code(new_code)

is_workflow_error()

Check if this is a workflow control error requiring special handling.

Workflow errors indicate issues with the service’s execution workflow, such as timeouts, maximum retry limits, or approval requirements. These errors typically require user intervention or service configuration changes.

Returns:

True if this is a workflow control error

Return type:

bool

Examples

Handling workflow errors with user notification:

>>> try:
...     await execute_code(code)
... except PythonExecutorException as e:
...     if e.is_workflow_error():
...         await notify_user(f"Execution failed: {e.message}")

should_retry_execution()

Determine if the same code execution should be retried.

Returns True for infrastructure errors where the code itself is likely correct but external dependencies (containers, network) caused the failure. This enables automatic retry of the same code without regeneration.

Returns:

True if execution should be retried with the same code

Return type:

bool

Examples

Automatic retry logic based on error category:

>>> if exception.should_retry_execution():
...     logger.info("Infrastructure issue, retrying execution...")
...     await retry_execution_with_backoff(code)

should_retry_code_generation()

Determine if code should be regenerated and execution retried.

Returns True for code-related errors where the generated code has issues that require regeneration with error feedback. This enables automatic code improvement through iterative generation.

Returns:

True if code should be regenerated and execution retried

Return type:

bool

Examples

Code regeneration retry logic:

>>> if exception.should_retry_code_generation():
...     logger.info("Code issue, regenerating with feedback...")
...     improved_code = await regenerate_with_feedback(str(exception))
...     await execute_code(improved_code)

Infrastructure Errors

ContainerConnectivityError

class osprey.services.python_executor.exceptions.ContainerConnectivityError(message, host, port, technical_details=None)

Bases: PythonExecutorException

Exception raised when Jupyter container is unreachable or connection fails.

This infrastructure error indicates that the Python executor service cannot establish communication with the configured Jupyter container endpoint. This typically occurs due to network issues, container startup problems, or configuration mismatches.

The error provides both technical details for debugging and user-friendly messages that abstract the underlying infrastructure complexity while preserving essential information for troubleshooting.

Parameters:

• message (str) – Technical error description for debugging

• host (str) – Container host address that failed to connect

• port (int) – Container port that failed to connect

• technical_details (Dict[str, Any], optional) – Additional technical information for debugging

Note

This error triggers automatic retry logic since the code itself is likely correct and the issue is with external infrastructure.

See also

ContainerConfigurationError : Configuration-related container issues PythonExecutorException.should_retry_execution : Retry logic for infrastructure errors

Examples

Handling container connectivity issues:

>>> try:
...     result = await container_executor.execute_code(code)
... except ContainerConnectivityError as e:
...     logger.warning(f"Container issue: {e.get_user_message()}")
...     # Automatic retry or fallback to local execution
...     result = await local_executor.execute_code(code)

Exception raised when Jupyter container is unreachable or connection fails.

Methods

get_user_message

Get user-friendly error message abstracting technical details.

__init__(message, host, port, technical_details=None)

get_user_message()

Get user-friendly error message abstracting technical details.

Provides a clear, non-technical explanation of the connectivity issue that users can understand without needing to know about container infrastructure details.

Returns:

User-friendly error description

Return type:

str

Examples

Displaying user-friendly error messages:

>>> error = ContainerConnectivityError(
...     "Connection refused", "localhost", 8888
... )
>>> print(error.get_user_message())
Python execution environment is not reachable at localhost:8888

ContainerConfigurationError

class osprey.services.python_executor.exceptions.ContainerConfigurationError(message, technical_details=None)

Bases: PythonExecutorException

Container configuration is invalid

Container configuration is invalid.

__init__(message, technical_details=None)

Code-Related Errors

CodeGenerationError

class osprey.services.python_executor.exceptions.CodeGenerationError(message, generation_attempt, error_chain, technical_details=None)

Bases: PythonExecutorException

LLM failed to generate valid code

LLM failed to generate valid code.

__init__(message, generation_attempt, error_chain, technical_details=None)

CodeSyntaxError

class osprey.services.python_executor.exceptions.CodeSyntaxError(message, syntax_issues, technical_details=None)

Bases: PythonExecutorException

Generated code has syntax errors

Generated code has syntax errors.

__init__(message, syntax_issues, technical_details=None)

CodeRuntimeError

class osprey.services.python_executor.exceptions.CodeRuntimeError(message, traceback_info, execution_attempt, technical_details=None, folder_path=None)

Bases: PythonExecutorException

Code failed during execution due to runtime errors

Code failed during execution due to runtime errors.

__init__(message, traceback_info, execution_attempt, technical_details=None, folder_path=None)

Workflow Errors

ExecutionTimeoutError

class osprey.services.python_executor.exceptions.ExecutionTimeoutError(timeout_seconds, technical_details=None, folder_path=None)

Bases: PythonExecutorException

Code execution exceeded timeout

Code execution exceeded timeout.

__init__(timeout_seconds, technical_details=None, folder_path=None)

MaxAttemptsExceededError

class osprey.services.python_executor.exceptions.MaxAttemptsExceededError(operation_type, max_attempts, error_chain, technical_details=None, folder_path=None)

Bases: PythonExecutorException

Maximum execution attempts exceeded

Maximum execution attempts exceeded.

__init__(operation_type, max_attempts, error_chain, technical_details=None, folder_path=None)

WorkflowError

class osprey.services.python_executor.exceptions.WorkflowError(message, stage, original_exception=None, technical_details=None, folder_path=None)

Bases: PythonExecutorException

Unexpected workflow error (bugs in our code, not user code)

Unexpected workflow error (bugs in framework code, not user code).

Methods

get_user_message

__init__(message, stage, original_exception=None, technical_details=None, folder_path=None)

get_user_message()

Return type:

str

Memory Operations Exceptions

MemoryCapabilityError

UserIdNotAvailableError

ContentExtractionError

MemoryFileError

MemoryRetrievalError

LLMCallError

Time Parsing Exceptions

TimeParsingError

InvalidTimeFormatError

AmbiguousTimeReferenceError

TimeParsingDependencyError

Exception Usage Patterns

Category-Based Error Handling

try:
    result = await executor.execute_code(code)
except PythonExecutorException as e:
    if e.should_retry_execution():
        # Infrastructure error - retry same code
        await retry_execution(code)
    elif e.should_retry_code_generation():
        # Code error - regenerate and retry
        new_code = await regenerate_code(error_feedback=str(e))
        await execute_code(new_code)
    else:
        # Workflow error - requires intervention
        await notify_user(f"Execution failed: {e.message}")

User-Friendly Error Messages

try:
    result = await container_executor.execute_code(code)
except ContainerConnectivityError as e:
    # Get user-friendly message abstracting technical details
    user_message = e.get_user_message()
    logger.warning(f"Container issue: {user_message}")
    # Technical details still available for debugging
    logger.debug(f"Technical details: {e.technical_details}")

Domain-Specific Error Handling

try:
    memory_result = await memory_capability.execute(state)
except UserIdNotAvailableError:
    # Handle missing user identification
    await request_user_identification()
except ContentExtractionError as e:
    # Handle content extraction failure
    logger.warning(f"Content extraction failed: {e}")
    # Try alternative extraction method
    await fallback_content_extraction()
except MemoryCapabilityError as e:
    # Handle general memory errors
    logger.error(f"Memory operation failed: {e}")

See also

Classification System

Error classification and severity management

Recovery Coordination

Recovery patterns and coordination strategies