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 framework.base.errors.FrameworkError

Bases: Exception

Base exception for all framework-related errors.

This is the root exception class for all custom exceptions within the ALS Expert 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 Alpha Berkeley Framework.

RegistryError

class framework.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 framework.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 framework.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 framework.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 framework.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 framework.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 framework.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 framework.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 framework.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 framework.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 framework.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 framework.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

class framework.capabilities.memory.MemoryCapabilityError

Bases: Exception

Base exception class for memory capability-specific errors.

Provides a hierarchy of memory-related exceptions to enable sophisticated error handling and classification. All memory capability errors inherit from this base class for consistent exception handling.

See also

MemoryOperationsCapability.classify_error() : Error classification for recovery strategies UserIdNotAvailableError : Specific error for missing user identification ContentExtractionError : Specific error for failed content extraction MemoryFileError : Specific error for storage system failures

Base exception class for memory capability-specific errors.

UserIdNotAvailableError

class framework.capabilities.memory.UserIdNotAvailableError

Bases: MemoryCapabilityError

Raised when user ID is not available in session configuration.

Memory operations require a valid user ID to associate stored content with the correct user account. This error indicates that the session configuration does not contain the required user identification.

User identification not available for memory operations.

ContentExtractionError

class framework.capabilities.memory.ContentExtractionError

Bases: MemoryCapabilityError

Raised when content extraction from chat history fails.

Indicates that the LLM-based content extraction process could not identify memory-worthy content in the conversation, or that the extraction process itself failed due to technical issues.

Content extraction from conversation failed.

MemoryFileError

class framework.capabilities.memory.MemoryFileError

Bases: MemoryCapabilityError

Raised when memory storage operations fail.

Indicates that the underlying memory storage system encountered an error during save or load operations. This could be due to file system issues, permission problems, or storage system failures.

Memory file system operations failed.

MemoryRetrievalError

class framework.capabilities.memory.MemoryRetrievalError

Bases: MemoryCapabilityError

Raised when memory retrieval operations fail.

Indicates that the system could not successfully retrieve stored memory entries, either due to storage system issues or data corruption problems.

Memory retrieval operations failed.

LLMCallError

class framework.capabilities.memory.LLMCallError

Bases: MemoryCapabilityError

Raised when LLM operations for memory processing fail.

Indicates that calls to the language model for content extraction, operation classification, or other memory-related analysis failed due to model errors, configuration issues, or service unavailability.

LLM operations for memory processing failed.

Time Parsing Exceptions

TimeParsingError

class framework.capabilities.time_range_parsing.TimeParsingError

Bases: Exception

Base exception class for time parsing-related errors.

Provides a hierarchy of time parsing exceptions to enable sophisticated error handling and classification. All time parsing errors inherit from this base class for consistent exception handling throughout the capability.

See also

TimeRangeParsingCapability.classify_error() : Error classification for recovery strategies InvalidTimeFormatError : Specific error for malformed time expressions AmbiguousTimeReferenceError : Specific error for unclear time references TimeParsingDependencyError : Specific error for missing dependencies TimeRangeParsingCapability.execute() : Main method that raises these errors

Base exception class for time parsing-related errors.

InvalidTimeFormatError

class framework.capabilities.time_range_parsing.InvalidTimeFormatError

Bases: TimeParsingError

Raised when time expressions cannot be parsed into valid datetime ranges.

Indicates that the LLM-based parsing process identified invalid time expressions, malformed date ranges, or logically inconsistent temporal references that cannot be converted to valid datetime objects.

Invalid time format in user input.

AmbiguousTimeReferenceError

class framework.capabilities.time_range_parsing.AmbiguousTimeReferenceError

Bases: TimeParsingError

Raised when time references are ambiguous or cannot be determined.

Indicates that the user query does not contain identifiable time references or contains ambiguous temporal expressions that cannot be resolved to specific datetime ranges without additional context.

Ambiguous time reference requiring clarification.

TimeParsingDependencyError

class framework.capabilities.time_range_parsing.TimeParsingDependencyError

Bases: TimeParsingError

Raised when required dependencies for time parsing are unavailable.

Indicates that the time parsing process requires additional context or dependencies that are not available in the current execution environment, such as missing query context or unavailable time reference data.

Missing required dependencies for time parsing.

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