Error Utilities

Utilities for converting structured errors to FastHTML responses, alerts, and error pages

Error to Alert Conversion

Convert structured errors from the cjm-error-handling library into FastHTML alert components.

---

source

error_to_alert

def error_to_alert(
    error:Any, # Error object (BaseError from cjm-error-handling or standard Exception)
    include_debug_info:bool=False, # Whether to include debug information in the alert
)->FT: # Alert component (error or warning)

Convert an error to an alert component.

Example: Converting Errors to Alerts

# Example 1: Standard exception
try:
    raise ValueError("Invalid configuration value")
except ValueError as e:
    alert_component = error_to_alert(e)
    print("Standard exception alert created")

# Example 2: Structured error (if library available)
if _has_error_handling:
    try:
        raise PluginError(
            message="Failed to load plugin",
            debug_info="Plugin class not found in module",
            context=ErrorContext(operation="load_plugin"),
            plugin_id="test_plugin"
        )
    except PluginError as e:
        alert_component = error_to_alert(e, include_debug_info=True)
        print("Structured error alert with debug info created")

Standard exception alert created
Structured error alert with debug info created

HTMX Error Response Utilities

Create HTMX-compatible error responses that can update specific page elements.

---

source

error_to_htmx_response

def error_to_htmx_response(
    error:Any, # Error object (BaseError or Exception)
    target_id:str='alert-container', # ID of element to update with error
    include_debug_info:bool=False, # Whether to include debug information
)->FT: # Alert component with correct ID for HTMX targeting

Create an HTMX-compatible error response.

# Example: HTMX error response
if _has_error_handling:
    error = ValidationError(
        message="Invalid form data",
        debug_info="Field 'port' must be between 1-65535",
        context=ErrorContext(operation="validate_form"),
        validation_errors={"port": "Out of range"}
    )
    htmx_response = error_to_htmx_response(error)
    print("HTMX error response created")

HTMX error response created

Error Page Components

Full-page error displays for critical failures or 404/500 errors.

---

source

create_error_page

def create_error_page(
    title:str='Error', # Page title
    message:str='An error occurred', # Main error message
    details:Optional=None, # Optional details or debug info
    show_home_link:bool=True, # Whether to show a link back to home
    home_path:str='/', # Path for the home link (defaults to root)
)->FT: # Div element containing the full error page

Create a full-page error display.

# Example: Create a 404 error page
create_error_page(
    title="Page Not Found",
    message="The page you're looking for doesn't exist",
    details="Error 404"
)

<div class="flex flex-col items-center justify-center text-center p-8 my-auto">
  <div class="mb-6">
<svg xmlns="http://www.w3.org/2000/svg" viewbox="0 0 24 24" fill="none" class="w-24 h-24 stroke-error"><path d="M12 9v2m0 4h.01m-6.938 4h13.856c1.54 0 2.502-1.667 1.732-3L13.732 4c-.77-1.333-2.694-1.333-3.464 0L3.34 16c-.77 1.333.192 3 1.732 3z" stroke-width="2" stroke-linecap="round" stroke-linejoin="round"></path></svg>  </div>
  <h1 class="text-3xl font-bold text-base-content mb-4">Page Not Found</h1>
  <p class="text-lg text-base-content/70 mb-2">The page you're looking for doesn't exist</p>
  <p class="text-sm text-base-content/50 mb-8">Error 404</p>
<a href="/" class="btn btn-primary">Go to Home</a></div>

---

source

error_to_page

def error_to_page(
    error:Any, # Error object (BaseError or Exception)
    include_debug_info:bool=False, # Whether to include debug information
    show_home_link:bool=True, # Whether to show a link back to home
    home_path:str='/', # Path for the home link (defaults to root)
)->FT: # Full error page component

Convert an error to a full-page error display.

# Example: Convert error to page
if _has_error_handling:
    error = WorkerError(
        message="Worker process crashed",
        debug_info="Worker PID 12345 terminated unexpectedly",
        context=ErrorContext(operation="worker_monitor", worker_pid=12345),
        worker_type="transcription",
        severity=ErrorSeverity.CRITICAL
    )
    error_page = error_to_page(error, include_debug_info=True)
    print("Error page created")

Error page created