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.

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.

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.