Enum CliError 

pub enum CliError {
    Session(SessionError),
    Pds(PdsError),
    NotLoggedIn,
    Http {
        url: String,
        source: Error,
    },
    CairnStatus {
        url: String,
        status: u16,
        body: String,
    },
    MalformedResponse {
        url: String,
        source: Error,
    },
    Config(String),
    KeyLoad(KeyLoadError),
    MigrationFailed(String),
    LeaseConflict {
        instance_id: String,
        age_secs: u64,
    },
    BindFailed {
        addr: SocketAddr,
        source: Error,
    },
    Startup(String),
    ServiceRecordDrift {
        pds_url: String,
        service_did: String,
        summary: String,
    },
    ServiceRecordAbsent {
        pds_url: String,
        service_did: String,
    },
    ServiceRecordUnreachable {
        pds_url: String,
        cause: String,
    },
    AuditDivergence {
        table: &'static str,
        row_id: i64,
        expected_hash: String,
        actual_hash: String,
        attested_rows_before_divergence: i64,
    },
}

Error sources the CLI dispatcher knows about. The human-readable Display output is what lands on stderr; CliError::exit_code maps variants onto the code table.

Variants

Session(SessionError)

Session-file failure (absent, permissions, ownership, version mismatch, malformed JSON).

Pds(PdsError)

PDS interaction failure (network, unauthorized, swap-race, unexpected status, malformed response).

NotLoggedIn

Authed command ran with no session file present.

Http

Transport-level failure contacting a Cairn server URL (timeout, DNS, TLS, connection refused).

Fields

url: String

URL that failed.

source: Error

Underlying reqwest error.

CairnStatus

Cairn returned a non-2xx HTTP status.

Fields

url: String

URL that returned the error.

status: u16

HTTP status code.

body: String

Response body for operator-side diagnostics.

MalformedResponse

Cairn returned a 2xx response but the body didn’t parse as the expected shape.

Fields

url: String

URL whose response failed to parse.

source: Error

Underlying serde_json error.

Config(String)

Argument-shape failure — malformed CLI inputs, config validation failures.

KeyLoad(KeyLoadError)

Signing key file couldn’t be loaded (§5.1 invariant failure, bad hex, wrong length, env-override attempt). Full cause lives on the nested KeyLoadError; Display never includes the key material because the key bytes are never decoded when an error path runs, and KeyLoadError::Display only formats paths + metadata.

MigrationFailed(String)

SQLite migrations failed at startup. String-only rather than wrapping sqlx’s error type to avoid leaking schema internals into the error taxonomy.

LeaseConflict

Another Cairn instance holds the single-instance lease (§F5). Distinct variant so operators + systemd can branch on the dedicated code::LEASE_CONFLICT exit code.

Fields

instance_id: String

Instance identifier held by the rival process.

age_secs: u64

Seconds since the rival last heartbeated.

BindFailed

TcpListener::bind failed — port in use, permission denied, malformed addr, etc.

Fields

addr: SocketAddr

Address we attempted to bind.

source: Error

Underlying I/O error.

Startup(String)

Anything in the startup sequence that doesn’t fit the buckets above (writer spawn, auth-context init). Rare at runtime; surfaces as INTERNAL.

ServiceRecordDrift

cairn serve startup verify (§F1, #8): the published app.bsky.labeler.service record on the operator’s PDS differs from what the local [labeler] config block would render. Reconcile via cairn publish-service-record.

Fields

pds_url: String

PDS URL the verify check fetched from.

service_did: String

Labeler service DID whose record was fetched.

summary: String

Per-field drift summary built by serve::verify. Not raw JSON — a human-readable enumeration of the fields that differ.

ServiceRecordAbsent

cairn serve startup verify (§F1, #8): no app.bsky.labeler.service record exists on the operator’s PDS for the labeler’s DID. The labeler hasn’t published its declaration yet.

Fields

pds_url: String

PDS URL the verify check fetched from.

service_did: String

Labeler service DID whose record was searched.

ServiceRecordUnreachable

cairn serve startup verify (§F1, #8): could not reach the PDS to perform the verify fetch. Transient infra issue, distinct from drift / absent — orchestrators should retry.

Fields

pds_url: String

PDS URL the verify check tried to fetch from.

cause: String

Underlying error message (transport, status, etc.).

AuditDivergence

cairn audit verify (#41) detected a hash-chain divergence. The walk recomputed row_id’s row_hash from its content + the running prev_hash and got expected_hash; the row’s stored actual_hash did not match. Distinct exit code (code::AUDIT_DIVERGENCE) so monitoring/CI can branch on integrity-failure vs. generic CLI error.

The dispatcher prints the verify outcome (human or JSON) to stdout before returning this error, so operators see the structured report on stdout and the same message on stderr alongside the non-zero exit. Stdout-only consumers (cairn audit verify --json) get the JSON line; the stderr echo is redundant for them but harmless.

Fields

table: &'static str

SQL-table name of the divergent row — "audit_log" or "pds_admin_audit". Added in #88 alongside the unified chain walker so operators can correlate (table, row_id) to a specific row across both tables in v1.7+ deployments.

row_id: i64

Primary key of the divergent row, scoped to the table named by table.

expected_hash: String

Hex-encoded SHA-256 the chain says this row’s row_hash should be (recomputed from the running prev_hash + the row’s stored content).

actual_hash: String

Hex-encoded SHA-256 actually stored in the row’s row_hash column.

attested_rows_before_divergence: i64

Number of rows whose hashes verified before this one — the truncation point operators reconcile from. Counts across both tables in the unified chain.

Implementations

impl CliError

pub fn exit_code(&self) -> i32

Exit code per criterion G. Kept close to the Display output so script authors can correlate message prefix with code.

Trait Implementations

impl Debug for CliError

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Display for CliError

fn fmt(&self, __formatter: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Error for CliError

fn source(&self) -> Option<&(dyn Error + 'static)>

Returns the lower-level source of this error, if any.

fn description(&self) -> &str

👎Deprecated since 1.42.0:

use the Display impl or to_string()

fn cause(&self) -> Option<&dyn Error>

👎Deprecated since 1.33.0:

replaced by Error::source, which can support downcasting

fn provide<'a>(&'a self, request: &mut Request<'a>)

🔬This is a nightly-only experimental API. (error_generic_member_access)

Provides type-based access to context intended for error reports.

impl From<KeyLoadError> for CliError

fn from(source: KeyLoadError) -> Self

Converts to this type from the input type.

impl From<PdsError> for CliError

fn from(source: PdsError) -> Self

Converts to this type from the input type.

impl From<SessionError> for CliError

fn from(source: SessionError) -> Self

Converts to this type from the input type.