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>.

This same check can also fail under an error kind of its own instead of credential_unverified. A failure that keeps the check from even starting its session, a missing agent binary (agent_not_found) or an invalid workspace path (invalid_workspace_cwd) most commonly, reports that kind unchanged, because the problem has nothing to do with the credential.

An agent that exits before it responds reports the early exit report under port_exit, including one that rejects its credential only by printing a message and exiting: the message it printed is the diagnosis.

And once the check’s one request is running, a failure whose own kind is non-retryable (for example turn_refused or turn_token_limit) or that is specifically an SSH connection failure (port_exit) also keeps that kind, because it already says something more specific than a credential failure would.

Every other way the request can fail to complete becomes credential_unverified: a retryable failure of a different kind, and, regardless of what else was happening, the request simply taking too long to answer.

Failure text is uniform across coding agents. A turn that exits 0 having written output, but no evidence that the model did any work, 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. A non-zero exit after the agent wrote output reports exit code N, except exit code 127, which reports agent_not_found.

A copilot-cli turn whose result event reports a failed exit reports the message of the last session.error event that turn, which is the model provider’s own message when the provider failed, and non-zero exit in result event when the runtime sent none.

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.

Early exit report

An agent that exits before it responds is reported the same way on every agent kind, on the credential check and on a working turn alike. The error kind is port_exit, retried with exponential backoff, and the message reads the agent runtime exited before responding: <status>. <status> is exit status N, or signal: <name> for a process ended by a signal Sortie did not send. The rest of the error text is the end of what the agent wrote to standard error:

agent: port_exit: the agent runtime exited before responding: exit status 2: error: unknown option '--sortie-unknown-switch'

What counts as responding depends on how the agent kind runs its runtime. A kind that starts a new process for every turn has responded once it writes a line on standard output that its adapter accepts as a response: a line the adapter’s decoder parses as a protocol message (claude-code, copilot-cli, opencode).

A line the decoder rejects is not a response, so a turn whose process exits before an accepted line takes this report whatever its exit status, 0 and 127 included, even if it wrote other, unreadable output first.

A kind that keeps one process for the whole session has responded once its startup handshake completes, so a runtime that exits during the handshake takes this report. Each agent adapter reference names its kind’s subprocess model and output format. A process Sortie stopped itself, on cancellation, a timeout, or shutdown, is never reported this way.

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.

Every detail above appears after an open .sortie directory: prefix in the full message. This error is retryable with exponential backoff. A run blocked this way never reaches the agent session.

Workspace preparation on the next attempt recreates a workspace directory that is missing (after_create runs again if configured), so that specific cause usually clears on its own; a workspace path still occupied by a symbolic link or another non-directory entry is rejected there instead, as a workspace conflict error (see Path errors above), so retries continue failing, under that different error, until the entry is removed by hand.

Worker exit kinds

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

The logs and the run history database keep the error text as Sortie recorded it, such as handoff withheld: absence of work observed under observed policy or agent turn 1: agent: turn_cancelled: turn cancelled: context canceled. The error of a run and of a retry in the HTTP API, and the retry’s last_error, serve a plain sentence for a withheld handoff, an agent error, a worker stage error, a failed CI check, a budget stop, and the reason a cancelled run was cancelled, such as Sortie stopped the session before the agent finished turn 1. or The agent sent no event within the stall timeout, so Sortie stopped the run. Any other error is served as recorded.

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 or run history"
  }
}

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 → …

A refusal by a provider usage limit that reports when it resets is the exception: the retry waits for that reset, past the cap, for at most 7 days.

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.