Enum HoldError 

pub enum HoldError {
    RepoNotFound(PathBuf),
    IndexError(Error),
    IoError {
        path: PathBuf,
        source: Error,
    },
    SerializationError(Box<dyn Error + Send + Sync>),
    DeserializationError(BoxedError),
    InvalidPath {
        message: String,
    },
    InvalidFileType(PathBuf, String),
    SetTimestampError(PathBuf, Error),
    CreateMetadataDirError(PathBuf, Error),
    InvalidMetadataSize(String, String),
    GcError(String),
    ConfigError(String),
    PartialFileProcessing {
        failed: usize,
        total: usize,
    },
    InvalidUtf8Path(PathBuf),
}

Error types that can occur in cargo-hold operations

Variants

RepoNotFound(PathBuf)

Git repository not found in the current directory or any parent.

Raised when git2::Repository::discover() fails or when the repository is bare (no working directory). cargo-hold requires a Git repository to determine which files to track for timestamp management.

Tuple Fields

0: PathBuf

The path where the Git repository was searched for

IndexError(Error)

Failed to read the Git index to enumerate tracked files.

Wraps errors from repo.index() when cargo-hold tries to read the list of files tracked by Git. The Git index contains the staged and tracked files that cargo-hold needs to manage.

IoError

File system I/O error during cargo-hold operations.

Common causes: permission denied, file not found, disk full, or memory mapping failures. Used throughout for file operations, directory creation/removal, and metadata access.

Fields

path: PathBuf

The path that caused the I/O error

source: Error

The underlying I/O error

SerializationError(Box<dyn Error + Send + Sync>)

Failed to serialize StateMetadata to rkyv format.

Occurs in save_metadata() when rkyv serialization fails. This is typically an internal error. The metadata file can be reset using cargo hold bilge.

DeserializationError(BoxedError)

Failed to deserialize metadata from rkyv format.

Occurs when loading metadata if the file is corrupted or from an incompatible format. cargo-hold automatically attempts recovery by resetting the metadata when this error is encountered.

Tuple Fields

0: BoxedError

The underlying deserialization error

InvalidPath

Git index path contains invalid UTF-8.

Raised when converting Git index entry paths from bytes to UTF-8 strings fails. All paths tracked by Git must be valid UTF-8 for cargo-hold to process them.

Fields

message: String

Description of why the path is invalid

InvalidFileType(PathBuf, String)

Attempted to process a non-regular file (symlink or directory).

cargo-hold only supports regular files. This error occurs when trying to hash, get size of, or set timestamps on symlinks or directories, which are explicitly unsupported.

Tuple Fields

0: PathBuf

The path of the invalid file

1: String

Description of the file type issue

SetTimestampError(PathBuf, Error)

Failed to restore a file’s modification time.

Occurs during the salvage operation when cargo-hold cannot open a file for writing or call set_modified(). Common causes are insufficient permissions or file system restrictions.

Tuple Fields

0: PathBuf

The file whose timestamp couldn’t be set

1: Error

The underlying I/O error

CreateMetadataDirError(PathBuf, Error)

Failed to create parent directory for metadata file.

Raised when fs::create_dir_all() fails while preparing to save metadata. The metadata file is typically stored at target/cargo-hold.metadata.

Tuple Fields

0: PathBuf

The directory path that couldn’t be created

1: Error

The underlying I/O error

InvalidMetadataSize(String, String)

Invalid size specification for –max-target-size.

Raised when parsing size strings like “5G” or “500M” fails. Valid suffixes are B (bytes), K (kilobytes), M (megabytes), G (gigabytes), or T (terabytes). Numbers without suffix are bytes.

Tuple Fields

0: String

The invalid size value provided

1: String

Description of the parsing error

GcError(String)

Cannot determine home directory for cargo cache cleanup.

Raised when home::cargo_home() returns None during garbage collection of ~/.cargo/registry or ~/.cargo/bin. The home directory is needed to locate cargo’s cache directories.

Tuple Fields

0: String

Description of the garbage collection error

ConfigError(String)

Metadata version is newer than supported or configuration invalid.

Raised when: 1) loaded metadata has version > METADATA_VERSION, indicating it was created by a newer cargo-hold version, or 2) required parameters are missing for the voyage command.

Tuple Fields

0: String

Description of the configuration error

PartialFileProcessing

One or more tracked files could not be hashed or read during stow/salvage.

The command stops instead of writing partial metadata or restoring timestamps for only a subset of files, which would make CI report success while incremental compilation state is wrong.

Fields

failed: usize

Number of files that failed

total: usize

Total tracked files attempted

InvalidUtf8Path(PathBuf)

PathBuf cannot be converted to UTF-8 string for storage.

Raised in StateMetadata operations when a PathBuf contains non-UTF-8 sequences. All paths must be valid UTF-8 for storage in the metadata format and compatibility with Git.

Tuple Fields

0: PathBuf

The path containing invalid UTF-8

Trait Implementations

impl Debug for HoldError

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

Formats the value using the given formatter.

impl Diagnostic for HoldError

fn code(&self) -> Option<Box<dyn Display + '_>>

Unique diagnostic code that can be used to look up more information about this Diagnostic. Ideally also globally unique, and documented in the toplevel crate’s documentation for easy searching. Rust path format (foo::bar::baz) is recommended, but more classic codes like E0123 or enums will work just fine.

fn help(&self) -> Option<Box<dyn Display + '_>>

Additional help text related to this Diagnostic. Do you have any advice for the poor soul who’s just run into this issue?

fn severity(&self) -> Option<Severity>

Diagnostic severity. This may be used by ReportHandlers to change the display format of this diagnostic.

fn url<'a>(&'a self) -> Option<Box<dyn Display + 'a>>

URL to visit for a more detailed explanation/help about this Diagnostic.

fn source_code(&self) -> Option<&dyn SourceCode>

Source code to apply this Diagnostic’s Diagnostic::labels to.

fn labels(&self) -> Option<Box<dyn Iterator<Item = LabeledSpan> + '_>>

Labels to apply to this Diagnostic’s Diagnostic::source_code

fn related<'a>( &'a self, ) -> Option<Box<dyn Iterator<Item = &'a dyn Diagnostic> + 'a>>

Additional related Diagnostics.

fn diagnostic_source(&self) -> Option<&dyn Diagnostic>

The cause of the error.

impl Display for HoldError

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

Formats the value using the given formatter.

impl Error for HoldError

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 HoldError

fn from(source: Error) -> Self

Converts to this type from the input type.