Enum HFError 

#[non_exhaustive]
pub enum HFError {
    Http {
        context: Box<HttpErrorContext>,
    },
    AuthRequired {
        context: Box<HttpErrorContext>,
    },
    RepoNotFound {
        repo_id: String,
        context: Option<Box<HttpErrorContext>>,
    },
    RevisionNotFound {
        repo_id: String,
        revision: String,
        context: Option<Box<HttpErrorContext>>,
    },
    EntryNotFound {
        path: String,
        repo_id: String,
        context: Option<Box<HttpErrorContext>>,
    },
    BucketNotFound {
        bucket_id: String,
        context: Option<Box<HttpErrorContext>>,
    },
    Forbidden {
        context: Box<HttpErrorContext>,
    },
    Conflict {
        context: Box<HttpErrorContext>,
    },
    RateLimited {
        retry_after: Option<Duration>,
        context: Box<HttpErrorContext>,
    },
    LocalEntryNotFound {
        path: String,
    },
    CacheNotEnabled,
    CacheLockTimeout {
        path: PathBuf,
    },
    Request {
        source: Error,
        url: Option<String>,
    },
    Io(Error),
    Json(Error),
    Url(ParseError),
    InvalidParameter(String),
    DiffParse(HFDiffParseError),
    Xet {
        operation: XetOperation,
        source: Box<dyn Error + Send + Sync>,
    },
    MalformedResponse {
        what: String,
        url: Option<String>,
    },
    Other(String),
}

Error type returned by public hf-hub APIs.

Match on the specific variants first for common Hub cases such as authentication, missing repos/files/revisions, forbidden access, and rate limiting. Lower-level transport failures use HFError::Request, while unmapped HTTP responses use HFError::Http.

This enum is #[non_exhaustive]: external matches must include a wildcard arm so new variants can be added without a SemVer break.

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.

Http

Non-success HTTP response that was not mapped to a more specific variant.

Fields

context: Box<HttpErrorContext>

Response metadata captured from the server.

AuthRequired

Authentication is required or the configured token was rejected.

Fields

context: Box<HttpErrorContext>

Response metadata captured from the server.

RepoNotFound

Repository was not found.

Fields

repo_id: String

Repository id, usually in owner/name form.

context: Option<Box<HttpErrorContext>>

Original HTTP response context, when available.

RevisionNotFound

Revision was not found within a repository.

Fields

repo_id: String

Repository id, usually in owner/name form.

revision: String

Missing revision name or commit SHA.

context: Option<Box<HttpErrorContext>>

Original HTTP response context, when available.

EntryNotFound

File or path was not found within a repository or bucket.

Fields

path: String

Missing repository-relative or bucket-relative path.

repo_id: String

Repository or bucket id associated with the lookup.

context: Option<Box<HttpErrorContext>>

Original HTTP response context, when available.

BucketNotFound

Bucket was not found.

Fields

bucket_id: String

Bucket id in owner/name form.

context: Option<Box<HttpErrorContext>>

Original HTTP response context, when available.

Forbidden

Credentials are valid, but the caller is not allowed to perform the operation.

Fields

context: Box<HttpErrorContext>

Response metadata captured from the server.

Conflict

Server reported a conflict, such as an already-existing resource or a branch head mismatch.

Fields

context: Box<HttpErrorContext>

Response metadata captured from the server.

RateLimited

Request was rate limited by the Hub.

Fields

retry_after: Option<Duration>

Parsed Retry-After delay, when the server returned one.

context: Box<HttpErrorContext>

Response metadata captured from the server.

LocalEntryNotFound

File was not found in the local cache during a cache-only lookup.

Fields

path: String

Missing cached path.

CacheNotEnabled

The operation requires the local cache, but caching is disabled.

CacheLockTimeout

Timed out waiting for an on-disk cache lock.

Fields

path: PathBuf

Path of the lock file or locked entry.

Request

Transport-level HTTP client error before a usable Hub response was produced.

Fields

source: Error

Underlying reqwest transport error.

url: Option<String>

Request URL, when known.

Io(Error)

Filesystem I/O error.

Json(Error)

JSON serialization or deserialization error.

Url(ParseError)

URL parsing error.

InvalidParameter(String)

Caller provided an invalid parameter value.

DiffParse(HFDiffParseError)

Raw diff parsing error.

Xet

A xet (high-performance content-addressable) operation failed.

The operation field identifies which step failed; source carries the underlying error (typically a xet_core error or a tokio join failure).

Fields

operation: XetOperation

Which xet operation produced the error.

source: Box<dyn Error + Send + Sync>

Underlying error, type-erased so the xet_core types stay out of the public API.

MalformedResponse

Hub responded with success but the response is missing data the client needs to proceed (e.g., an ETag or X-Repo-Commit header that should always be present, or a 304 Not Modified without a corresponding cached state).

Distinct from Http: the status code was a success, the shape of the response was wrong.

Fields

what: String

Short description of what was missing or unexpected.

url: Option<String>

URL of the request that produced the bad response, when known.

Other(String)

Catch-all error for cases that do not fit another variant.

Implementations

impl HFError

pub fn xet<E>(operation: XetOperation, source: E) -> Self

where E: Error + Send + Sync + 'static,

Construct an HFError::Xet from a typed source error.

The source is type-erased into Box<dyn Error + Send + Sync> so that upstream xet_core types stay out of the public API; downstream matchers can use source.downcast_ref::<T>() if they need the concrete type.

pub fn malformed_response(what: impl Into<String>) -> Self

Construct a HFError::MalformedResponse without a known URL.

pub fn malformed_response_at( what: impl Into<String>, url: impl Into<String>, ) -> Self

Construct a HFError::MalformedResponse with the originating URL attached.

Trait Implementations

impl Debug for HFError

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

Formats the value using the given formatter.

impl Display for HFError

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

Formats the value using the given formatter.

impl Error for HFError

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 HFError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for HFError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for HFError

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<HFDiffParseError> for HFError

fn from(source: HFDiffParseError) -> Self

Converts to this type from the input type.

impl From<ParseError> for HFError

fn from(source: ParseError) -> Self

Converts to this type from the input type.