Error Handling Guidelines

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• pyproject.toml
• codex.md
• examples/README.md
• examples/advanced_processing_example.py
• docker/README.md

Error handling in the FLEXT platform is governed by a strict architectural philosophy centered on type safety, functional programming patterns, and zero-tolerance for silent failures. The system prioritizes the "Railway Pattern" using specialized result containers to manage fallible operations without relying on ad-hoc exception propagation for control flow.

The core objective is to ensure that every integration built on FLEXT follows typed and validated primitives. This approach eliminates bypasses, shims, and untyped error dictionaries, replacing them with a canonical r[T] contract for all fallible application paths.

Sources: AGENTS.md:275-279, examples/README.md:94-98

Core Principles

The FLEXT engineering law defines several non-negotiable principles for handling errors and system state:

• Railway Pattern: Use r[T] for all fallible paths. Ad-hoc error dicts or raw exceptions for control flow are prohibited.
• Root Cause Resolution: Every defect must be fixed at the source. Workarounds, shims, or suppressions are not permitted.
• Absolute Truth: Claims regarding system state or errors must be backed by objective evidence (exact commands, exit status, and decisive output).
• Continuous Green: The project must remain in a valid, importable state at all times. Any non-green state is treated as an incident.

Sources: AGENTS.md:154-180, AGENTS.md:275-278, codex.md:24-25

The Railway Pattern Flow

The following diagram illustrates how the Railway Pattern manages the transition between success and failure states in a processing pipeline.

Explanation: In the Railway Pattern, a failure at any stage diverts the execution to the "Failure Path" (the red track), preventing further operations and returning a type-safe error result.
Sources: examples/README.md:94-98, examples/advanced_processing_example.py:126-136

Implementation Details

Result Containers (r[T])

FLEXT utilizes specialized result types to wrap return values. These containers provide methods to check status and safely unwrap values or handle errors.

Component	Description
r[T]	Canonical result wrapper for fallible paths.
.is_success	Property indicating the operation completed without error.
.failure	Property indicating the operation encountered an error.
.unwrap()	Method to retrieve the value; typically used after verifying success.
.fail(msg)	Method to generate a failure result with a specific message.

Sources: examples/README.md:148-154, examples/advanced_processing_example.py:126-140

Processing & Validation Metrics

For complex operations like batch processing or parallel validation, FLEXT employs specific data structures to track success and failure rates.

class ProcessingResult(m.BaseModel):
    """Result of processing operation with metrics."""
    operation_id: str = u.Field(description="Unique operation identifier")
    items_processed: int = u.Field(description="Total items processed")
    items_succeeded: int = u.Field(description="Items that succeeded")
    items_failed: int = u.Field(description="Items that failed")
    errors: t.StrSequence = u.Field(default_factory=tuple)

Sources: examples/advanced_processing_example.py:96-110

Infrastructure Error Handling

Infrastructure components, specifically Docker-based testing environments, implement automated state recovery to handle failures.

Container Lifecycle State Machine

Explanation: When a test fails, the container is marked as "dirty" in ~/.flext/docker_state.json. On the subsequent run, the system automatically purges the dirty container and its volumes to ensure a clean state.
Sources: docker/README.md:150-175

Error Handling in Development

The development workflow enforces error checking through a series of "Quality Gates" and specific commands.

• qlty: The first command to run for discovery of smells or defects.
• make check: Runs linting, formatting, and type checks (MyPy/Pyright).
• Validation Batch: Per file batch (≤5 files), developers must run smoke tests and type checks.
• Bead Ledger: All evidence of failures, including command output and exit codes, must be recorded in the bd (Bead) system.

Sources: AGENTS.md:173-180, AGENTS.md:214-222, codex.md:13-14, pyproject.toml:681-710

Technical Requirements for Error Definitions

FLEXT projects must adhere to strict typing and configuration rules when defining error states:

1. Strict Typing: Use of Any or bare object is strictly prohibited. Error structures must be fully typed.
2. Pydantic Integration: Use model_validate(kwargs) for dynamic payloads to ensure runtime safety during error reporting.
3. No Fallbacks: Silent defaults or hardcoded bypasses for error conditions are considered governance violations.

Sources: AGENTS.md:155-160, AGENTS.md:286-290, codex.md:19-21

Summary

Error handling in FLEXT is not merely a coding practice but a governance requirement. By utilizing the Railway Pattern (r[T]), enforcing strict type safety through Pydantic, and maintaining a "Continuous Green" infrastructure, the platform ensures that failures are handled explicitly, transparently, and safely. Developers are expected to use the canonical r facade and recorded evidence in the Bead system to maintain the integrity of the integrated data platform.