Errors

Every error Sortie produces falls into one of six categories: startup failures, tracker errors, agent errors, workspace errors, worker exit outcomes, and HTTP API errors. This page documents each - what it means, whether Sortie retries it, and what you should do.

Error kind strings appear in logs exactly as shown below. Search this page for the string you see in your output. For step-by-step diagnosis of the most common failures, see How to troubleshoot common failures.

Startup and configuration errors

These errors prevent Sortie from starting. They appear immediately on launch and cause exit code 1. None are retryable - Sortie exits. Fix the configuration and restart.

Preflight validation reports all failures at once in a single dispatch preflight failed: ... line.

The sortie validate subcommand runs these same checks without starting the orchestrator, and additionally emits advisory warnings for front matter issues (unknown keys, sub-keys, type mismatches) and template problems (dot-context misuse in {{ range }}/{{ with }}, unknown variables, unknown sub-fields). Use it in CI pipelines or pre-commit hooks to catch configuration errors, typos, and template mistakes before deployment.

Tracker errors

Errors from tracker adapter API calls. They appear in logs with the format tracker: <kind>: <message>.

Three are configuration errors (before any API calls). Six occur at runtime during polling, state transitions, or issue fetches.

Configuration errors

Runtime errors

Agent errors

Errors from agent adapter sessions. They appear in logs with the format agent: <kind>: <message>.

Workspace errors

Errors during workspace preparation and hook execution. Two distinct error types.

Path errors

Format: workspace <op>: <details>

Occur when Sortie prepares the per-issue workspace directory.

Hook errors

Format: hook <op>: <details>

Occur when lifecycle hook scripts (after_create, before_run, after_run, before_remove) execute.

Hook errors in after_create prevent the worker from starting - the error is retryable. Hook errors in before_remove are logged but ignored; workspace cleanup still proceeds.

Worker exit kinds

Not errors per se, but essential for understanding session outcomes. Appear in logs as worker exiting exit_kind=<kind>.

SSH worker errors

When extensions.worker.ssh_hosts is configured, two exit codes carry special meaning.

HTTP API errors

The JSON API returns errors in a standard envelope:

{
  "error": {
    "code": "issue_not_found",
    "message": "issue identifier \"FOO-999\" not found in current state"
  }
}

For full endpoint documentation, request/response shapes, and curl examples, see HTTP API reference.

Retry behavior

Exponential backoff - retryable errors schedule the next attempt with:

delay = min(10000ms × 2^(attempt-1), max_retry_backoff_ms)

With the default max_retry_backoff_ms of 300,000 (5 minutes), the progression is: 10s → 20s → 40s → 80s → 160s → 300s → 300s → …

Non-retryable errors release the claim immediately. The issue becomes dispatchable again on the next poll cycle if it’s still in an active tracker state.

Continuation retries fire after a normal worker exit when max_turns was reached but the issue remains active. These use a fixed 1-second delay - no exponential backoff.

The backoff cap is configurable via agent.max_retry_backoff_ms in WORKFLOW.md.