Enum LinkError 

pub enum LinkError {
    NoHub,
    NoCredential,
    BadKey,
    UnboundCredential,
    BadAgentKey {
        message: String,
    },
    UnsafeHub {
        hub: String,
    },
    Transport {
        hub: String,
        message: String,
    },
    Http {
        what: &'static str,
        status: u16,
        message: String,
        code: Option<String>,
        details: Option<Value>,
    },
    NotJson {
        what: &'static str,
        status: u16,
    },
    ResponseTooLarge {
        limit_bytes: u64,
    },
    BadAddress {
        given: String,
        reason: String,
    },
    BadGrantId {
        given: String,
    },
    UnsafePath {
        path: String,
    },
    PushTooLarge {
        detail: String,
    },
    ProposeTooLarge {
        bytes: u64,
    },
    NotUtf8 {
        path: String,
    },
    InvalidPack {
        message: String,
    },
    InvalidFeed {
        message: String,
    },
    AliasRebindRequired {
        alias: String,
        from: String,
        to: String,
    },
    Conflict {
        paths: Vec<String>,
    },
    ConflictBundle {
        bundle: String,
        paths: Vec<String>,
    },
    LocalPolicyTransition {
        paths: Vec<String>,
    },
    BulkPreviewRequired {
        preview: Value,
    },
    ScopedProjectionModified,
    ScopedViewChanged,
    BrainUnavailable,
    RemoteAdvancedDuringSync,
    UnsupportedPlatform {
        operation: &'static str,
    },
    Io(Error),
    Store(StoreError),
}

Everything that can go wrong on the wire or at its edges. Each variant maps onto one stable CLI error code; messages are single-line and never echo the credential.

Variants

NoHub

No hub URL was configured anywhere (flag, env, .dbmd/config).

NoCredential

The verb needs a credential and none was present.

BadKey

The credential contains whitespace / non-ASCII (a paste artifact). The key is deliberately not echoed.

UnboundCredential

A store selected the destination while an ambient credential was present, but the operator did not bind that credential to the same origin. This is a hard refusal, not an anonymous fallback: silently dropping a credential can turn an intended private operation into a confusing public one.

BadAgentKey

The agent signing key file named by AGENT_KEY_FILE_ENV is missing, unreadable, or not a valid Ed25519 PKCS#8 — key material is never echoed.

Fields

message: String

What failed, without any key material.

UnsafeHub

A non-HTTPS hub outside loopback: the bearer key would travel in cleartext.

Fields

hub: String

The offending hub URL.

Transport

TCP/TLS-level failure: the hub never answered.

Fields

hub: String

The hub base URL.

message: String

The transport-layer error text.

Http

The hub answered with an HTTP error status.

Fields

what: &'static str

What the client was doing (e.g. "resolve", "sync pull").

status: u16

The HTTP status code.

message: String

The hub’s own error string when it sent one, else a placeholder.

code: Option<String>

The hub’s machine code field when it sent one.

details: Option<Value>

Permission-filtered structured refusal details, when supplied.

NotJson

A 2xx whose body is not JSON — a captive portal, a proxy, or a wrong URL — refused here rather than deserializing into nothing downstream.

Fields

what: &'static str

What the client was doing.

status: u16

The (2xx) status that carried the non-JSON body.

ResponseTooLarge

The hub response exceeded the selected endpoint’s byte cap.

Fields

limit_bytes: u64

The endpoint-specific cap applied before JSON parsing.

BadAddress

A malformed @brain/id address.

Fields

given: String

The raw address as typed.

reason: String

Why it did not parse.

BadGrantId

A grant id whose shape cannot travel as a URL path segment.

Fields

given: String

The raw id as typed.

UnsafePath

An exported file path that would escape or pollute the destination (absolute, .., a dot-leading segment, or an illegal character). The hub is not trusted with local path layout.

Fields

path: String

The offending path as received.

PushTooLarge

The store exceeds the hub’s bounded whole-snapshot caps.

Fields

detail: String

Which cap was hit, human-readable.

ProposeTooLarge

The propose body exceeds the hub’s inbox cap.

Fields

bytes: u64

The offending body size in bytes.

NotUtf8

A store file that is not valid UTF-8 cannot travel the JSON push path.

Fields

path: String

The store-relative path of the offending file.

InvalidPack

A downloaded pack failed validation before any local write.

Fields

message: String

Hash, ZIP, path, count, or expansion failure.

InvalidFeed

A signed feed entry, hash chain, or advertised feed head did not verify.

Fields

message: String

The failed integrity condition, without untrusted secret material.

AliasRebindRequired

A mutable alias moved to another canonical brain. Ordinary sync fails closed; only the exact old/new ids can authorize replacing that one alias binding while preserving both canonical trust histories.

Fields

alias: String

from: String

to: String

Conflict

Local and remote both changed one or more coordinates since the last verified sync baseline. No side was overwritten.

Fields

paths: Vec<String>

Bounded, portable paths safe to show to the agent/operator.

ConflictBundle

A readable v2 conflict was preserved as a private, exact-head bundle. The bundle is local control state; none of its bytes ride with the brain, and resolving it always creates a fresh explicit mutation.

Fields

bundle: String

Local ULID naming .dbmd/conflicts/<bundle>/plan.json.

paths: Vec<String>

Bounded, readable conflict paths.

LocalPolicyTransition

.sevralocal newly made paths eligible to ride. Uploading them is an explicit adoption boundary, never an accidental side effect of editing or removing a local policy file.

Fields

paths: Vec<String>

Bounded local-only paths. They are never sent in telemetry.

BulkPreviewRequired

The exact mutation crosses a permissioned bulk-impact boundary. The hub has not committed it; preview is the bounded, permission-filtered receipt an agent must inspect before explicitly confirming the same request.

Fields

preview: Value

Stable structured preview returned by the hub.

ScopedProjectionModified

A scoped checkout’s generated store marker was edited or removed. It is local projection metadata and is never accepted as brain data.

ScopedViewChanged

The effective permission slice changed after this checkout was pinned. Reusing the directory could conceal removals or accidentally adopt files revealed by a wider grant, so a new checkout is required.

BrainUnavailable

A v2 identity/head was previously accepted for this ref, but the hub now hides it. Never reinterpret that as a v1 downgrade.

RemoteAdvancedDuringSync

The verified remote head advanced while a pull or post-commit barrier was in flight. The old baseline is deliberately retained.

UnsupportedPlatform

This build cannot provide the no-follow, directory-handle-relative filesystem semantics required for trust/key/snapshot state.

Fields

operation: &'static str

The operation that requires hardened local filesystem primitives.

Io(Error)

Local filesystem failure while materializing a pull or reading a push.

Store(StoreError)

A store-level failure (walking the local store for a push).

Trait Implementations

impl Debug for LinkError

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

Formats the value using the given formatter.

impl Display for LinkError

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

Formats the value using the given formatter.

impl Error for LinkError

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<Error> for LinkError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<StoreError> for LinkError

fn from(source: StoreError) -> Self

Converts to this type from the input type.