on failure

on failure

Error handling block that catches failures from preceding steps. When a step in a flow fails (HTTP timeout, LLM error, permission denial, runtime exception), execution jumps to the on failure block instead of halting the machine. The error context is available for logging, fallback logic, or graceful degradation.

When to use

Use on failure when you need to:

• Provide a fallback response when an API call fails
• Log errors and continue with a default value
• Retry with different parameters or a different approach
• Send alert notifications when a step fails
• Gracefully degrade instead of returning an error to the caller

Use decide for expected branching logic (not error recovery). Use ensures > guards for input/output validation that should block execution before it starts. Use runtime > max_retries for automatic retry of transient failures.

Syntax

Flow-level error handling

flow <name>
  <steps>
  on failure
    <recovery steps>

Inline in implicit main flow

implements
  <steps>
  on failure
    <recovery steps>

Error context

Inside the on failure block, the error is available through:

Reference	Description
error.message	Human-readable error description
error.step	Name of the step that failed
error.type	Error category (e.g., "timeout", "permission_denied", "runtime")
error.details	Additional error-specific data (varies by error type)

Examples

Fallback response on API failure

machine weather_service
  accepts
    city as text, is required

  responds with
    temperature as number
    source as text

  implements
    action fetch_weather http
      url: "https://api.weather.com/v1/current?city=${input.city}"
      timeout: 3000

    compute format
      {temperature: fetch_weather.data.temp, source: "live"}

    on failure
      compute fallback
        {
          temperature: null,
          source: "unavailable",
          error: error.message
        }

Log error and notify

machine critical_pipeline
  accepts
    data as map, is required

  implements
    flow process
      ask analyze, using: "anthropic:claude-sonnet-4-6"
        with task "Analyze this data for anomalies.\n\nData: ${JSON.stringify(input.data)}"
        returns
          anomalies as list
        assuming
          anomalies: []

      action store_results call
        machine: "@myorg/data/store"
        results: steps.analyze.anomalies

      on failure
        launch send_alert
          machine: "@mashin/actions/notifications/send"
          channel: "slack"
          message: "Pipeline failed at step " + error.step + ": " + error.message

        compute error_response
          {
            status: "failed",
            failed_step: error.step,
            error_type: error.type,
            message: error.message
          }

Retry with different strategy

machine resilient_classifier
  accepts
    text as text, is required

  implements
    flow classify
      ask primary, using: "anthropic:claude-sonnet-4-6"
        with task "Classify this text.\n\nText: ${input.text}"
        returns
          category as text
          confidence as number
        assuming
          category: "general"
          confidence: 0.8

      compute result
        {category: steps.primary.category, model: "primary"}

      on failure
        // Fall back to a smaller, faster model
        ask fallback, using: "anthropic:claude-haiku-4"
          with task "Classify this text into a category.\n\nText: ${input.text}"
          returns
            category as text
          assuming
            category: "general"

        compute result
          {category: steps.fallback.category, model: "fallback"}

Multiple flows with independent error handling

machine etl_pipeline
  implements
    flows
      flow extract
        action fetch http
          url: input.source_url
        on failure
          compute extract_error
            {status: "extract_failed", error: error.message}

      flow transform
        compute process
          {data: steps.fetch.body}
        on failure
          compute transform_error
            {status: "transform_failed", error: error.message}

      flow load
        action store db
          query: "INSERT INTO results (data) VALUES ($1)"
          params: [steps.process.data]
        on failure
          compute load_error
            {status: "load_failed", error: error.message}

Governance

The on failure block is control flow. It does not require its own permissions. However:

• Steps inside the on failure block are governed normally. An ask step in the recovery path still requires reason capability and is recorded in the behavioral ledger.
• The failure event itself is recorded as a step event, including the error type, failed step name, and error message.
• If the on failure block itself fails, the machine halts with the secondary error. There is no nested error handling.

The behavioral ledger records both the original failure and the recovery path, making the full error-and-recovery sequence auditable (Inv 6: Trace Integrity).

Translations

Language	Keyword
English	on failure
Spanish	en caso de fallo
French	en cas d’echec
German	bei Fehler
Japanese	失敗したら
Chinese	失败时
Korean	실패 시

See also

• decide - For expected branching (not error recovery)
• ensures - Guards for input/output validation
• implements - The section where on failure blocks live
• launch - Often used inside on failure to send alerts