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

 error_to_alert (error:Any, include_debug_info:bool=False)

Convert an error to an alert component.

Type Default Details
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
Returns FT Alert component (error or warning)

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

 error_to_htmx_response (error:Any, target_id:str='alert-container',
                         include_debug_info:bool=False)

Create an HTMX-compatible error response.

Type Default Details
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
Returns FT Alert component with correct ID for HTMX targeting 
# 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

 create_error_page (title:str='Error', message:str='An error occurred',
                    details:Optional[str]=None, show_home_link:bool=True,
                    home_path:str='/')

Create a full-page error display.

Type Default Details
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)
Returns FT Div element containing the full error page 
# 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

 error_to_page (error:Any, include_debug_info:bool=False,
                show_home_link:bool=True, home_path:str='/')

Convert an error to a full-page error display.

Type Default Details
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)
Returns FT Full error page component 
# 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