Enum BackendError 

pub enum BackendError {
    BucketNotFound {
        kind: BackendKind,
        name: String,
    },
    NotAuthorized {
        kind: BackendKind,
        action: String,
        name: String,
    },
    Network {
        source: BoxError,
    },
    InvalidCredentials {
        source: ObjectStoreError,
    },
    UnknownStoredEngine {
        kind: BackendKind,
        stored: String,
    },
    EngineMismatch {
        kind: BackendKind,
        url_engine: StorageEngine,
        stored_engine: StorageEngine,
    },
}

Errors surfaced by build.

The Display strings (no colons, “user” prefix on NotAuthorized) are the single source of truth for the operator-facing wording rendered by fatal_message.

Invariant for backend-specific wording

Every variant whose Display string mentions the storage container (“bucket” / “container”) must carry a kind: BackendKind field and route the noun through [container_word]. Hardcoded “bucket” / “container” literals in the format string are a bug — they leak S3 vocabulary into Azure diagnostics (and vice versa). New variants must follow the same pattern as BackendError::BucketNotFound.

Invariant for fatal_message

fatal_message walks the error source chain starting one level past err.source(), because any variant with a #[source] field already embeds {source} in its Display format string (making the first level visible without chain-walking). Every future variant that adds a #[source] field must also include {source} in its format string. Omitting {source} while keeping #[source] causes fatal_message to silently drop the first source level from the rendered message.

Invariant for Network classification

When [classify] or validate_format encounter ObjectStoreError::Network, they extract the inner BoxError and store it directly in BackendError::Network::source. They must never wrap the whole ObjectStoreError::Network (whose own Display is "network error: <inner>") into another BackendError variant whose Display also includes the source — that produces the redundant "network error: network error: ..." rendering fatal_message is documented to avoid. New ObjectStoreError variants that carry transport semantics must either add a dedicated BackendError::Network-style classification arm or store the inner cause directly.

Variants

BucketNotFound

Bucket (S3) or container (Azure) does not exist. Maps from a 404 / NoSuchBucket on the construction-time probe.

Fields

kind: BackendKind

Which backend reported the failure.

name: String

Bucket or container name.

NotAuthorized

Authentication succeeded but the principal lacks the listed action on the named bucket/container. Maps from a 403 / AccessDenied on the probe.

Fields

kind: BackendKind

Which backend reported the failure.

action: String

SDK call name the principal was denied (e.g. ListObjectsV2).

name: String

Bucket or container name.

Network

Transport-level failure during backend construction (probe or FORMAT key read): DNS resolution failed, connection refused, TLS handshake error, or request timeout. This indicates a URL or network configuration problem — not a credentials problem. The inner error is extracted from ObjectStoreError::Network and stored directly to avoid the redundant “network error: network error” display that would result from wrapping it whole.

Fields

source: BoxError

The underlying transport error preserved for chain-walking.

InvalidCredentials

Catch-all for credential acquisition failures (missing AWS profile, expired creds, missing Azure credential alias, …).

Fields

source: ObjectStoreError

The underlying ObjectStoreError preserved as #[source].

UnknownStoredEngine

The FORMAT key records an engine name this binary does not support.

The supported-engine list is rendered from StorageEngine::supported_list_str so adding a new variant updates this message automatically.

Fields

kind: BackendKind

Which backend reported the failure.

stored: String

The engine name as written in the FORMAT key.

EngineMismatch

The ?engine= URL parameter conflicts with the engine stored in the FORMAT key.

Fields

kind: BackendKind

Which backend reported the failure.

url_engine: StorageEngine

Engine requested via the ?engine= URL parameter.

stored_engine: StorageEngine

Engine stored in the FORMAT key.

Trait Implementations

impl Debug for BackendError

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

Formats the value using the given formatter.

impl Display for BackendError

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

Formats the value using the given formatter.

impl Error for BackendError

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<BackendError> for ProtocolError

fn from(source: BackendError) -> Self

Converts to this type from the input type.

impl From<BackendError> for RemoteError

fn from(source: BackendError) -> Self

Converts to this type from the input type.