hf_fetch_model/
error.rs

1// SPDX-License-Identifier: MIT OR Apache-2.0
2
3//! Error types for hf-fetch-model.
4//!
5//! All fallible operations in this crate return [`FetchError`].
6//! [`FileFailure`] provides structured per-file error reporting.
7
8use std::path::PathBuf;
9
10/// Errors that can occur during model fetching.
11#[derive(Debug, thiserror::Error)]
12#[non_exhaustive]
13pub enum FetchError {
14    /// The hf-hub API returned an error.
15    #[error("hf-hub API error: {0}")]
16    Api(#[from] hf_hub::api::tokio::ApiError),
17
18    /// An I/O error occurred while accessing the local filesystem.
19    #[error("I/O error at {path}: {source}")]
20    Io {
21        /// The path that caused the error.
22        path: PathBuf,
23        /// The underlying I/O error.
24        source: std::io::Error,
25    },
26
27    /// The repository was not found or is inaccessible.
28    #[error("repository not found: {repo_id}")]
29    RepoNotFound {
30        /// The repository identifier that was not found.
31        repo_id: String,
32    },
33
34    /// Authentication failed (missing or invalid token).
35    ///
36    /// Reserved for future use. Currently, auth failures surface as
37    /// [`FetchError::Api`] because hf-hub does not distinguish them.
38    #[error("authentication failed: {reason}")]
39    Auth {
40        /// Description of the authentication failure.
41        reason: String,
42    },
43
44    /// An invalid glob pattern was provided for filtering.
45    #[error("invalid glob pattern: {pattern}: {reason}")]
46    InvalidPattern {
47        /// The glob pattern that failed to parse.
48        pattern: String,
49        /// Description of the parse error.
50        reason: String,
51    },
52
53    /// SHA256 checksum mismatch after download.
54    #[error("checksum mismatch for {filename}: expected {expected}, got {actual}")]
55    Checksum {
56        /// The filename that failed verification.
57        filename: String,
58        /// The expected SHA256 hex digest.
59        expected: String,
60        /// The actual SHA256 hex digest computed from the file.
61        actual: String,
62    },
63
64    /// A download operation timed out.
65    #[error("timeout downloading {filename} after {seconds}s")]
66    Timeout {
67        /// The filename that timed out.
68        filename: String,
69        /// The timeout duration in seconds.
70        seconds: u64,
71    },
72
73    /// One or more files failed to download.
74    ///
75    /// Contains the successful path and a list of per-file failures.
76    #[error("{} file(s) failed to download:{}", failures.len(), format_failures(failures))]
77    PartialDownload {
78        /// The snapshot directory (if any files succeeded).
79        path: Option<PathBuf>,
80        /// Per-file failure details.
81        failures: Vec<FileFailure>,
82    },
83
84    /// A chunked (multi-connection) download failed.
85    #[error("chunked download failed for {filename}: {reason}")]
86    ChunkedDownload {
87        /// The filename that failed.
88        filename: String,
89        /// Description of the failure.
90        reason: String,
91    },
92
93    /// An HTTP request to the `HuggingFace` API failed.
94    #[error("HTTP error: {0}")]
95    Http(String),
96
97    /// An invalid argument was provided.
98    #[error("{0}")]
99    InvalidArgument(String),
100
101    /// The repository exists but no files matched after filtering,
102    /// or the repository contains no files at all.
103    #[error("no files matched in repository {repo_id}")]
104    NoFilesMatched {
105        /// The repository identifier.
106        repo_id: String,
107    },
108}
109
110/// A per-file download failure with structured context.
111#[derive(Debug, Clone)]
112pub struct FileFailure {
113    /// The filename that failed.
114    pub filename: String,
115    /// Human-readable description of the failure.
116    pub reason: String,
117    /// Whether this failure is likely to succeed on retry.
118    pub retryable: bool,
119}
120
121impl std::fmt::Display for FileFailure {
122    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
123        write!(
124            f,
125            "{}: {} (retryable: {})",
126            self.filename, self.reason, self.retryable
127        )
128    }
129}
130
131/// Formats a list of file failures for inclusion in the `PartialDownload` error message.
132fn format_failures(failures: &[FileFailure]) -> String {
133    let mut s = String::new();
134    for f in failures {
135        s.push_str("\n  - ");
136        s.push_str(f.filename.as_str());
137        s.push_str(": ");
138        s.push_str(f.reason.as_str());
139    }
140    s
141}
hf_fetch_model/error.rs

hf_fetch_model/
error.rs
