Error Types

Swarm defines 6 error enums using thiserror, each covering a distinct subsystem. All error types implement std::error::Error and can be converted to anyhow::Error at the orchestrator level.

ConfigError

Configuration errors — fatal at startup.

Variant	Display Message	When It Occurs
`MissingFile { path }`	`config file not found at {path}`	`~/.swarm/settings.json` doesn't exist
`ParseError { reason }`	`failed to parse config: {reason}`	JSON syntax error, file read failure, or path canonicalization failure
`ValidationError { reason }`	`config validation failed: {reason}`	Empty agents list, invalid names, duplicate names, bad provider references, invalid WASM capabilities
`VersionMismatch { found, expected }`	`config version {found} is not supported (expected {expected})`	Config version is newer than supported

GitError

Git prerequisite and worktree operation errors — fatal at startup or during worktree ops.

Variant	Display Message	When It Occurs
`NotARepo { path }`	`{path} is not a git repository`	Project directory is not a git repo
`DirtyTree`	`working tree has uncommitted changes; commit or stash first`	Uncommitted changes without `--stash` flag
`WorktreeOp { reason }`	`git worktree operation failed: {reason}`	Worktree create/remove/lock/unlock/merge failure, HEAD is detached
`VersionTooOld { found, required }`	`git version {found} is too old; swarm requires git >= {required}`	Git version below 2.20

MailboxError

Mailbox and SQLite errors — DB-open is fatal, transient locks are retried.

Variant	Display Message	When It Occurs
`DbOpen { reason }`	`failed to open mailbox database: {reason}`	SQLite connection failure, schema creation failure, invalid enum values
`DbLocked { reason }`	`mailbox database is locked: {reason}`	WAL lock contention, query failure
`UnknownAgent { name }`	`unknown agent: {name}`	Message sent to non-existent agent
`SelfSend`	`agent cannot send a message to itself`	Agent tries to send a message to itself
`NotFound { id }`	`message not found: {id}`	Reply to a non-existent message ID

AgentError

Agent lifecycle errors — spawn failures may be retried with backoff.

Variant	Display Message	When It Occurs
`SpawnFailed { name, reason }`	`failed to spawn agent {name}: {reason}`	Backend session failed to start
`Timeout { name, seconds }`	`agent {name} timed out after {seconds}s`	Agent session exceeded timeout

WorkflowError

Workflow definition errors — parse, validation, or inheritance failures.

Variant	Display Message	When It Occurs
`NotFound { name }`	`workflow not found: {name}`	Referenced workflow doesn't exist
`ParseError { reason }`	`failed to parse workflow: {reason}`	YAML/JSON parse failure
`ValidationError { reason }`	`workflow validation failed: {reason}`	General validation failure
`CyclicDependency { cycle }`	`circular dependency detected in workflow stages: {cycle}`	Stage dependency graph has a cycle
`CyclicInheritance { chain }`	`circular inheritance detected: {chain}`	Workflow `extends` chain has a cycle
`DuplicateStage { name }`	`duplicate stage name: {name}`	Two stages have the same name
`InvalidStageName { name }`	`invalid stage name '{name}': must match [a-z][a-z0-9_-]*`	Stage name contains invalid characters
`UnknownDependency { stage, dep }`	`unknown dependency '{dep}' in stage '{stage}'`	Stage depends on non-existent stage
`ParentNotFound { child, parent }`	`parent workflow '{parent}' not found for extends in '{child}'`	`extends` references missing workflow
`CyclicWorkflowRef { chain }`	`circular workflow_ref detected: {chain}`	Nested workflow references form a cycle
`MissingWorkflowRef { stage }`	`workflow_ref stage '{stage}' is missing required 'workflow' field`	Stage type is `workflow_ref` but no workflow specified
`IoError { reason }`	`I/O error: {reason}`	File system errors during workflow loading

SessionError

Session lifecycle errors — stale sessions prompt user action.

Variant	Display Message	When It Occurs
`ActiveSession { id, pid }`	`session {id} is already active (pid {pid})`	Attempting to create session when one already exists
`StaleLockfile { path }`	`stale lockfile found at {path}; another session may be running`	Lockfile exists but process state is ambiguous
`RecoveryNeeded`	`previous session did not shut down cleanly; recovery is needed`	Session artifacts remain from crashed session
`IoError { reason }`	`session I/O error: {reason}`	File read/write/delete failures

Error Handling Strategy

Swarm follows ADR-009:

Library code uses thiserror enums for precise error types
Binary/orchestrator uses anyhow for ergonomic error propagation
All thiserror types automatically convert to anyhow::Error via the ? operator

ADR-009: Error Handling — Design rationale
Agent Lifecycle — How errors affect agent state
State Transitions — Error-triggered transitions

swarm