Error Handling

What happens when a step fails? By default: the pipeline stops immediately and returns an error. That's the safe default — better to fail loudly than silently produce wrong results.

But sometimes you want something smarter. You might want to retry a flaky network call, use a fallback value, or just keep going despite a failure. That's what JigSpec's error handling features are for.

Default behavior

If a step fails and you haven't configured error handling, the pipeline stops:

PipelineError: Step "fetch_data" failed: Connection timeout after 30s
Pipeline halted at step 2 of 5

This is intentional. Partial results are often worse than no results.

Retry with max_attempts

Implemented

For ai steps, you can configure how many times JigSpec will retry if the model call fails:

- name: analyze
  action: ai
  prompt: "Analyze this data: {{ input.text }}"
  config:
    max_attempts: 3   # try up to 3 times before failing

Retries use exponential backoff — each retry waits a bit longer than the last. This handles transient API errors and rate limits gracefully.

Default retry behavior

The default value for max_attempts is 1 (no retry). Set it to 3 for production pipelines that make external API calls.

Pipeline-level error policy

Spec Only

You can set a pipeline-wide error policy that applies to all steps:

pipeline:
  name: my-pipeline
  on_error: stop   # stop (default) | continue | rollback

The three policies:

Policy	Behavior
stop	Halt the pipeline at the first failure (default)
continue	Mark the failed step, keep running other steps
rollback	Attempt to undo side effects before stopping

Not yet implemented

Pipeline-level on_error policy is defined in the spec but not yet implemented in the JigSpec runtime. Pipelines always use the stop policy today.

Step-level error handling

Spec Only

For fine-grained control, configure error handling per step:

- name: risky_call
  action: code
  run: |
    const resp = await fetch(input.url)
    return { body: await resp.text() }
  outputs:
    - body
  on_error:
    retry: 3                   # retry up to 3 times
    backoff: exponential       # wait longer between retries
    fallback: default_value    # use this step's output if all retries fail

- name: default_value
  action: ai
  prompt: "Generate a default response since the fetch failed"

The fallback field names another step to use in place of the failed step's output. This lets you build resilient pipelines that degrade gracefully.

Not yet implemented

Step-level on_error with fallback and backoff policies are defined in the spec but not yet implemented. Only max_attempts on ai steps is currently supported.

Cost safety: max_cost

Spec Only

For agent pipelines that might make many model calls, you can set a cost limit:

pipeline:
  name: research-agent
  config:
    max_cost: 1.00   # stop if estimated cost exceeds $1.00

If the pipeline's estimated cost exceeds max_cost, it stops and returns an error rather than running up an unexpected bill.

Not yet implemented

max_cost is defined in the spec but not yet implemented. Agent pipelines currently have no built-in cost limit — use max_attempts to bound the number of tool call rounds instead.