Overview

Date: 2026-05-11

Time: 15:48

Overview

This is a Phase 6 example script demonstrating error handling patterns in FTL2 automation. It covers the full spectrum of error detection and response — from checking whether failures occurred, to inspecting individual errors, to controlling execution flow with fail_fast mode. The examples progress from simple error checks to recommended production patterns including execution summaries.

Usage Patterns

Basic error checking after execution:

async with automation(quiet=True) as ftl:
    await ftl.file(path="/tmp/test.txt", state="touch")
    await ftl.command(cmd="echo 'Hello'")
    
    if ftl.failed:
        for error in ftl.errors:
            print(f"[{error.host}] {error.module}: {error.error}")

Fail-fast mode — stop on first error:

try:
    async with automation(fail_fast=True) as ftl:
        await ftl.some_module(...)  # Raises AutomationError on failure
except AutomationError as e:
    print(f"Module: {e.result.module}")
    print(f"Host: {e.result.host}")
    print(f"Error: {e.result.error}")

Recommended production pattern — summarize results:

async with automation(quiet=True) as ftl:
    await ftl.file(path="/tmp/config", state="directory")
    await ftl.file(path="/tmp/config/app.yml", state="touch")
    
    success_count = sum(1 for r in ftl.results if r.success)
    changed_count = sum(1 for r in ftl.results if r.changed)
    
    if ftl.failed:
        for error in ftl.errors:
            print(f"[{error.host}:{error.module}] {error.error}")
        return False
    return True

API and Configuration

| Property/Parameter | Type | Description |

|---|---|---|

| ftl.failed | bool | True if any operation failed |

| ftl.errors | list[ExecuteResult] | List of failed result objects |

| ftl.error_messages | list[str] | List of error message strings only |

| ftl.results | list[ExecuteResult] | All results (success and failure) |

| fail_fast=True | automation() kwarg | Stop execution on first error, raises AutomationError |

ExecuteResult fields on failure: success (False), changed (False), error (string message), module (which module failed), host (which host failed), output (dict with failure details).

AutomationError attributes: message (str), result (the failed ExecuteResult).

Key Behaviors

• Default behavior is continue-on-error. All operations execute regardless of individual failures. Errors are collected and inspectable after the run.
• fail_fast=True raises AutomationError immediately on the first module failure, stopping all subsequent operations.
• AutomationContext can be constructed directly (not just via async with automation()), useful for testing or building custom execution flows.
• Error inspection is granular: each ExecuteResult in ftl.errors carries the host, module name, and error message, enabling per-host or per-module error reporting.
• error_messages is a convenience accessor that returns just the string messages without the full result objects.

Relationships

• Imports: ftl2.automation (the automation context manager, AutomationContext class, AutomationError exception), ftl2.ftl_modules.ExecuteResult (the result type for module execution).
• Uses modules: file (touch/directory), command (shell commands), service, copy, deploy — all shown in error scenarios.
• Pattern context: This is the error-handling layer that wraps around all module execution shown in earlier phase examples. The ftl.results list accumulates across all module calls within a single async with automation() block.