Enum WorkspaceError 

#[non_exhaustive]
pub enum WorkspaceError {
    NotFound {
        path: String,
    },
    VersionConflict(WorkspaceVersionConflict),
    RemoteGitConflict(RemoteGitConflict),
    InvalidArgument {
        message: String,
    },
    Timeout {
        op: String,
        duration: Duration,
    },
    Unsupported(String),
    Backend(Error),
}

Error type returned by every WorkspaceFileSystem and friend trait method.

#[non_exhaustive] so adding a new variant in a future release is a minor change — existing match callers compile, they just hit the catch-all arm for unknown variants.

The variants intentionally split into three categories:

• Structured failures the trait surface knows how to describe (NotFound, InvalidArgument, Timeout, Unsupported). New variants in this category should also be structured.
• Typed conflicts with their own payload structs that already ship as part of the public API (VersionConflict(WorkspaceVersionConflict), RemoteGitConflict(RemoteGitConflict)).
• Backend(anyhow::Error) — the escape hatch. Any failure not covered above wraps an anyhow::Error. Backends should prefer the typed variants where they apply; Backend is for genuinely opaque or backend-specific failures.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

NotFound

A read / list against a path that does not exist on the backend.

Backends that distinguish “doesn’t exist” from “exists but access denied” should still emit this for the former; the latter belongs in Backend(_) with the backend’s native auth error wrapped.

Fields

path: String

Path that triggered the failure, in workspace-relative form where possible. May include backend-specific qualifiers (s3://bucket/key) when that aids debugging.

VersionConflict(WorkspaceVersionConflict)

Compare-and-swap write rejected because the in-storage version no longer matches what the caller observed at read time. Carries the existing public WorkspaceVersionConflict struct verbatim.

RemoteGitConflict(RemoteGitConflict)

A remote git server returned 409 / 422 with a typed conflict code (e.g. BRANCH_EXISTS, WORKING_TREE_DIRTY, NOTHING_TO_STASH). Carries the existing public RemoteGitConflict struct verbatim.

InvalidArgument

Caller passed an argument the backend cannot honour (empty version on a CAS write, malformed pattern on a search, path with parent-traversal, …). Backends should prefer this over Backend(_) for caller-fault errors so the model can reason about retry strategy.

Fields

message: String

Human-readable description; safe to surface to the model.

Timeout

The operation’s outer timeout (see WorkspaceServices::operation_timeout) fired before the backend responded.

Fields

op: String

Human-readable operation name, e.g. read_text or s3.get_object.

duration: Duration

Configured timeout that expired.

Unsupported(String)

The backend explicitly does not support this operation.

Used by adapters that wrap a partial trait surface (e.g. the remote git backend rejecting worktree operations even though WorkspaceGit is implemented).

Backend(Error)

Catch-all wrapping a lower-level error that does not map to one of the typed variants above. This is the bridge between the existing anyhow::Result world and the typed surface — when a backend throws a generic I/O / HTTP / SDK error it ends up here.

Implementations

impl WorkspaceError

pub fn from_anyhow(err: Error) -> Self

Convert an anyhow::Error to a WorkspaceError, preserving the typed variant when the original cause was one of the known conflict structs.

Into::into (auto-derived from the #[from] anyhow::Error variant) drops every anyhow::Error into the Backend arm because at the value level anyhow::Error has type-erased its source. Use this helper instead when migrating code paths that today emit anyhow::Error::new(WorkspaceVersionConflict { .. }) or anyhow::Error::new(RemoteGitConflict { .. }) — the typed variant survives the round-trip.

// Old code:
fn legacy() -> anyhow::Result<()> { ... }
// New caller:
let typed = WorkspaceError::from_anyhow(legacy().unwrap_err());
match typed {
    WorkspaceError::VersionConflict(v) => retry(v),
    other => return Err(other),
}

Trait Implementations

impl Debug for WorkspaceError

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

Formats the value using the given formatter.

impl Display for WorkspaceError

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

Formats the value using the given formatter.

impl Error for WorkspaceError

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 WorkspaceError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<RemoteGitConflict> for WorkspaceError

fn from(source: RemoteGitConflict) -> Self

Converts to this type from the input type.

impl From<WorkspaceVersionConflict> for WorkspaceError

fn from(source: WorkspaceVersionConflict) -> Self

Converts to this type from the input type.