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), template problems (dot-context misuse in {{ range }}/{{ with }}, unknown variables, unknown sub-fields), and a configuration value that cannot reach the agent it is written for. 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>.

Failure text is uniform across coding agents. A turn that exits 0 having produced nothing reports agent exited without producing output, followed by the signals the adapter looked for and did not find. An adapter that reads both model-authored content and tool-call activity reports agent exited without producing output: no message from the agent and no tool call, which covers claude-code, copilot-cli, and opencode. kiro reads only the first, so it reports agent exited without producing output: no message from the agent. A non-zero exit reports exit code N. A runtime that reported no turn outcome and gave the adapter no process exit to observe reports runtime reported no turn outcome. A runtime whose protocol defines a task-completion report, but that ended the turn without one, reports agent stopped without reporting the task complete.

Workspace errors

Errors during workspace preparation, hook execution, and the control-file writes that follow.

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.

Control-file errors

Format: mcp config generation: <details>

Occur while the worker writes the MCP tool-server configuration (.sortie/mcp.json and .sortie/.gitignore), after the workspace is ready but before the agent session starts.

This error is retryable with exponential backoff. A run blocked this way never reaches the agent session, and keeps retrying until whatever replaced .sortie is fixed.

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 applies to retryable errors. The next attempt is scheduled 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 with no exponential backoff.

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