Error Handling

AXON treats failure as a first-class citizen. Unlike traditional programming languages where errors are afterthoughts, AXON’s error handling is deeply integrated into the language design, runtime, and execution model.

Philosophy

Fail Gracefully, Heal AutomaticallyAXON programs don’t just crash — they self-heal through adaptive retry, semantic validation, and failure context injection.

Every error in AXON carries structured diagnostic context and is handled according to a strict severity hierarchy.

The 6-Level Error Hierarchy

Errors are ordered from least to most critical. Each level has specific semantics, recovery strategies, and runtime behavior.

Level 1: ValidationError

Output type doesn’t match declaration

Level 2: ConfidenceError

Confidence score below configured floor

Level 3: AnchorBreachError

Hard constraint anchor violated

Level 4: RefineExhaustedError

Max retry attempts exceeded

Level 5: ModelCallError

LLM API call failed

Level 6: ExecutionTimeoutError

Execution time limit exceeded

Level 1: ValidationError

When It Happens

Raised by the SemanticValidator when a step’s output fails epistemic type checking.

step Extract {
  ask: "What is your opinion on this contract?"
  output: FactualClaim  // ❌ Model returned Opinion, not FactualClaim
}

Error Structure

Location: /axon/runtime/runtime_errors.py:119

runtime_errors.py

class ValidationError(AxonRuntimeError):
    """Output type does not match the declared semantic type.
    
    Example:
        Step declares `-> FactualClaim` but the model
        produced content classified as `Opinion`.
    """
    level: int = 1

Recovery Strategy

Automatic Refinement
Explicit Handling
Propagate

If refine block configured:

step Extract {
  refine {
    max_attempts: 3
    pass_failure_context: true
  }
  ask: "Extract factual claims only"
  output: FactualClaim
}

The retry engine re-invokes with:

Previous attempt failed: ValidationError — Expected FactualClaim, got Opinion.
Please provide only verifiable facts, not subjective opinions.

Catch in flow logic:

step Extract {
  ask: "Extract claims"
  output: FactualClaim
  on_error: ValidationError -> fallback("default_claims")
}

Level 2: ConfidenceError

When It Happens

Raised when the model’s self-reported confidence falls below the configured threshold.

persona Expert {
  domain: ["medicine"]
  confidence_threshold: 0.85  // Require 85%+ confidence
}

step Diagnose {
  as Expert
  ask: "What is the diagnosis?"
  output: Diagnosis  // ❌ Model confidence: 0.62 < 0.85
}

Error Structure

runtime_errors.py

class ConfidenceError(AxonRuntimeError):
    """Confidence score fell below the configured floor.
    
    Example:
        Persona requires `confidence >= 0.85` but the model
        self-reported confidence of 0.62.
    """
    level: int = 2

Recovery Strategy

Increase Depth

reason {
  depth: 5  // More reasoning steps
}

Request More Context

context DetailedAnalysis {
  depth: exhaustive
  max_tokens: 8192
}

Use Tool

use WebSearch {
  query: "latest research on [topic]"
}

Fallback

on_error: ConfidenceError -> AgnosticFallback

Design Choice: Low confidence is treated as an error, not a warning. AXON programs must explicitly handle uncertainty.

Level 3: AnchorBreachError

When It Happens

Raised when a hard constraint (anchor) is violated. Anchors represent inviolable rules.

contract_analyzer.axon

anchor NoHallucination {
  require: source_citation
  confidence_floor: 0.75
  unknown_response: "I don't have sufficient information."
  on_violation: raise AnchorBreachError
}

step Extract {
  constrained_by [NoHallucination]
  ask: "What was the contract date?"
  output: FactualClaim  // ❌ Model speculated without citation
}

Error Structure

runtime_errors.py

class AnchorBreachError(AxonRuntimeError):
    """A hard constraint (anchor) was violated.
    
    Example:
        Anchor `NoHallucination` requires `factual_only`
        but the output contains speculative claims.
    """
    level: int = 3

Anchor Types

Epistemic Anchors
Logical Anchors
Safety Anchors

Enforce information quality:

NoHallucination — Block unverified claims
RequiresCitation — Demand explicit sources
AgnosticFallback — Penalize speculation

Enforce reasoning structure:

SyllogismChecker — Validate logical format
ChainOfThoughtValidator — Require step markers

Enforce behavioral constraints:

NoHarmfulContent — Block dangerous outputs
PrivacyGuard — Prevent PII leakage

Recovery Strategy

Anchor breaches always trigger refinement if configured:

step Extract {
  constrained_by [NoHallucination]
  refine {
    max_attempts: 3
    pass_failure_context: true  // Inject breach details
  }
  ask: "Extract contract parties"
  output: EntityMap
}

On retry, the model receives:

Anchor breach detected: NoHallucination
Violation: Output contained unverified claim without citation.
Required: All factual claims must include source attribution.

Critical: If refinement exhausted or not configured, AnchorBreachError propagates. Anchors are never ignored.

Level 4: RefineExhaustedError

When It Happens

Raised by the RetryEngine when all retry attempts fail.

step Extract {
  refine {
    max_attempts: 3
    backoff: exponential
  }
  ask: "Extract parties"
  output: EntityMap
}
// After 3 failed attempts:
// ❌ RefineExhaustedError: All attempts exhausted

Error Structure

Location: /axon/runtime/runtime_errors.py:177

runtime_errors.py

class RefineExhaustedError(AxonRuntimeError):
    """All refine/retry attempts have been exhausted.
    
    Example:
        `refine { max_attempts: 3 }` — three attempts
        failed validation, no more retries available.
    """
    level: int = 4

Error Context

Includes all attempt records:

ErrorContext(
  step_name="Extract",
  flow_name="AnalyzeContract",
  attempt=3,
  details="Attempts: [
    {attempt: 1, error: 'ValidationError'},
    {attempt: 2, error: 'AnchorBreachError'},
    {attempt: 3, error: 'ValidationError'}
  ]"
)

Recovery Strategy

on_exhaustion Fallback

refine {
  max_attempts: 3
  on_exhaustion: fallback("conservative_extract")
}

on_exhaustion Skip

refine {
  on_exhaustion: skip  // Continue with empty result
}

Propagate to Caller

Default behavior — error propagates up the stack

Level 5: ModelCallError

When It Happens

Raised when the LLM API call itself fails (not the model’s output). Common Causes:

Network timeout
Rate limiting (HTTP 429)
Invalid API key (HTTP 401)
Model overload (HTTP 503)
Malformed request

Error Structure

runtime_errors.py

class ModelCallError(AxonRuntimeError):
    """The LLM API call itself failed.
    
    Example:
        Anthropic API returned HTTP 429 (rate limited)
        during step `analyze_contract`.
    """
    level: int = 5

Recovery Strategy

Automatic Retry (Backend)
Fallback Backend
Circuit Breaker (Planned)

Most backends have built-in retry with exponential backoff:

anthropic.py

async def call_model(self, prompt: str) -> str:
    for attempt in range(self.max_retries):
        try:
            return await self._make_request(prompt)
        except RateLimitError:
            await asyncio.sleep(2 ** attempt)  # Exponential backoff
    raise ModelCallError("Rate limit exceeded after retries")

Switch to alternative model:

run Analyze(doc)
  as Expert
  backend: anthropic
  fallback_backend: openai  // Use GPT-4 if Claude fails

Level 6: ExecutionTimeoutError

When It Happens

Raised when execution exceeds configured time limit.

context RealTimeAnalysis {
  max_execution_time: 30s  // 30 second limit
}

run SlowFlow(largeDoc)
  within RealTimeAnalysis
  // ❌ Took 45s → ExecutionTimeoutError

Error Structure

runtime_errors.py

class ExecutionTimeoutError(AxonRuntimeError):
    """Execution exceeded the configured time limit.
    
    Example:
        Flow `deep_analysis` configured with 30s timeout
        but the model took 45s to respond.
    """
    level: int = 6

Recovery Strategy

Increase Timeout

context Thorough {
  max_execution_time: 300s
}

Reduce Scope

step QuickAnalysis {
  depth: shallow
  max_tokens: 1024
}

Async Execution (Planned)

Phase 6: Background execution with callbacks

Early Termination

Flow terminates immediately, returns partial results

Timeout errors cannot be refined — they indicate infrastructure issues, not semantic failures.

Self-Healing Mechanism

AXON’s adaptive retry engine creates a closed feedback loop between the model and runtime.

How It Works

Step Execution

Model produces output for a step

Validation

Runtime checks type, confidence, anchors

Failure Detected

ValidationError, ConfidenceError, or AnchorBreachError

Failure Context Injection

Exact error details injected into next prompt:

Previous attempt failed:
- Error: ValidationError
- Expected: FactualClaim
- Received: Opinion
- Reason: Output contained subjective judgment

Please retry with only verifiable facts.

Adaptive Retry

Model learns from mistake and tries again

Backoff Strategy

Optional delay between attempts:

none: Immediate retry
linear: 1s, 2s, 3s, …
exponential: 0.5s, 1s, 2s, 4s, 8s, …

Configuration

Full refinement config

step Extract {
  refine {
    max_attempts: 3
    pass_failure_context: true  // Inject error details
    backoff: exponential         // Wait between retries
    on_exhaustion: fallback("conservative_extract")
    on_exhaustion_target: "ConservativeExtractFlow"
  }
  constrained_by [NoHallucination]
  ask: "Extract contract terms"
  output: Terms
}

Guarantees

Strict Boundaries: Self-healing respects max_attempts. If the model fails to heal within limits, AXON raises RefineExhaustedError — no infinite loops.

Anchor Dependency: Healing effectiveness depends on anchor precision. Clear, logical anchors enable successful recovery. Ambiguous anchors may cause syntactic fixes without semantic improvement.

Tracing and Diagnostics

Every error is automatically traced with full context.

Trace Events

program.trace.json

{
  "event_type": "step_error",
  "timestamp": "2026-03-06T10:15:32Z",
  "step_name": "Extract",
  "flow_name": "AnalyzeContract",
  "error": {
    "type": "ValidationError",
    "level": 1,
    "message": "Expected FactualClaim, got Opinion",
    "context": {
      "step_name": "Extract",
      "flow_name": "AnalyzeContract",
      "attempt": 1,
      "expected_type": "FactualClaim",
      "actual_value": "I think the contract is risky"
    }
  }
}

View Traces

axon trace program.trace.json

Outputs human-readable execution timeline with errors highlighted.

Error Propagation

Errors propagate up the call stack unless handled:

Exit Codes:

0 — Success
1 — Validation/Confidence/Anchor error
2 — Refine exhausted
3 — Model call failed
4 — Execution timeout
5 — Compilation error

Best Practices

Always Configure Refinement

Don’t rely on default error propagation:

step Critical {
  refine { max_attempts: 3 }
  // ...
}

Use Precise Anchors

Vague anchors lead to poor self-healing:❌ anchor Reasonable { /* vague */ }
✅ anchor RequiresCitation { require: source_citation }

Set Realistic Confidence Thresholds

Too high = constant failures, too low = unreliable:

Exploratory: 0.6
Standard: 0.75
High-stakes: 0.85+

Monitor Traces in Production

Save traces for post-mortem analysis:

axon run program.axon --trace --trace-output prod.trace.json

Handle Level 5-6 Errors Explicitly

Infrastructure errors need different handling than semantic errors:

on_error: ModelCallError -> retry(max_attempts: 5)
on_error: ExecutionTimeoutError -> abort("infrastructure_issue")

Comparison with Traditional Error Handling

Feature	Try-Catch (Python)	Result Types (Rust)	AXON
Semantic errors	❌	❌	✅
Automatic retry	❌	❌	✅
Failure context injection	❌	❌	✅
Typed error hierarchy	Partial	✅	✅
Self-healing	❌	❌	✅
Epistemic tracking	❌	❌	✅

Next Steps

Cognitive Primitives

Learn about refine, anchor, validate

Type System

Understand ValidationError triggers

Compilation Pipeline

See where errors are detected

Runtime Reference

Deep dive into executor and validator

Get Started

Core Concepts

Language Reference

Examples

​Philosophy

​The 6-Level Error Hierarchy

​Level 1: ValidationError

​When It Happens

​Error Structure

​Recovery Strategy

​Level 2: ConfidenceError

​When It Happens

​Error Structure

​Recovery Strategy

Increase Depth

Request More Context

Use Tool

Fallback

​Level 3: AnchorBreachError

​When It Happens

​Error Structure

​Anchor Types

​Recovery Strategy

​Level 4: RefineExhaustedError

​When It Happens

​Error Structure

​Error Context

​Recovery Strategy

​Level 5: ModelCallError

​When It Happens

​Error Structure

​Recovery Strategy

​Level 6: ExecutionTimeoutError

​When It Happens

​Error Structure

​Recovery Strategy

Increase Timeout

Reduce Scope

Async Execution (Planned)

Early Termination

​Self-Healing Mechanism

​How It Works

​Configuration

​Guarantees

​Tracing and Diagnostics

​Trace Events

​View Traces

​Error Propagation

​Best Practices

​Comparison with Traditional Error Handling

​Next Steps

Cognitive Primitives

Type System

Compilation Pipeline

Runtime Reference

Build docs developers (and LLMs) love

Philosophy

The 6-Level Error Hierarchy

Level 1: ValidationError

When It Happens

Error Structure

Recovery Strategy

Level 2: ConfidenceError

When It Happens

Error Structure

Recovery Strategy

Level 3: AnchorBreachError

When It Happens

Error Structure

Anchor Types

Recovery Strategy

Level 4: RefineExhaustedError

When It Happens

Error Structure

Error Context

Recovery Strategy

Level 5: ModelCallError

When It Happens

Error Structure

Recovery Strategy

Level 6: ExecutionTimeoutError

When It Happens

Error Structure

Recovery Strategy

Self-Healing Mechanism

How It Works

Configuration

Guarantees

Tracing and Diagnostics

Trace Events

View Traces

Error Propagation

Best Practices

Comparison with Traditional Error Handling

Next Steps