Enum Error 

#[non_exhaustive]
pub enum Error {
    #[non_exhaustive]
    Internal {
        message: String,
        source: Option<Box<dyn Error + Send + Sync>>,
    },
    #[non_exhaustive]
    VerificationRejected {
        reason: Option<String>,
    },
    #[non_exhaustive]
    ChecksumMismatch {
        expected: String,
        computed: String,
    },
    Aborted,
    #[non_exhaustive]
    NotFound {
        url: String,
    },
    #[non_exhaustive]
    Unauthorized {
        status: u16,
        url: String,
    },
    #[non_exhaustive]
    HttpStatus {
        status: u16,
        url: String,
    },
    #[non_exhaustive]
    NoReleaseFound {
        target: Option<String>,
    },
    #[non_exhaustive]
    MissingAssetField {
        field: String,
    },
    #[non_exhaustive]
    InvalidResponse {
        source: Box<dyn Error + Send + Sync>,
    },
    #[non_exhaustive]
    MissingField {
        field: &'static str,
    },
    NoCurrentVersion,
    #[non_exhaustive]
    InvalidHeader {
        source: Box<dyn Error + Send + Sync>,
    },
    #[non_exhaustive]
    InvalidAuthToken {
        source: Box<dyn Error + Send + Sync>,
    },
    #[non_exhaustive]
    InvalidCertificate {
        source: Box<dyn Error + Send + Sync>,
    },
    #[non_exhaustive]
    InvalidProgressStyle {
        source: Box<dyn Error + Send + Sync>,
    },
    Io(Error),
    Zip(Box<dyn Error + Send + Sync>),
    Json(Box<dyn Error + Send + Sync>),
    Transport(Box<dyn Error + Send + Sync>),
    SemVer(Box<dyn Error + Send + Sync>),
    ArchiveNotEnabled(String),
    CompressionNotEnabled(String),
    NoSignatures(ArchiveKind),
    Signature(Box<dyn Error + Send + Sync>),
    #[non_exhaustive]
    InvalidAssetName {
        name: String,
    },
    SignatureNonUTF8,
    S3Auth(Box<dyn Error + Send + Sync>),
}

The crate’s single public error type.

Matching on variants

Error is #[non_exhaustive], so a match must include a wildcard arm. For programmatic decisions, prefer http_status() and url() over matching on the Display string — the Display strings are human-facing and may change between minor releases.

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.

#[non_exhaustive]

Internal

An internal invariant of the update pipeline was violated, or an internal task failed.

This signals a bug or an unexpected condition (the extractor source has no file name, a required path was not found in an archive, an archive path was not valid UTF-8, or a blocking task failed to join), not a normal failure mode a caller can act on. When the failure wraps an underlying error (e.g. a tokio JoinError), it is carried as source and surfaced via std::error::Error::source.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

message: String

Human-readable description of the violated invariant / failed task.

source: Option<Box<dyn Error + Send + Sync>>

The underlying error, when this wraps one (e.g. a tokio JoinError); else None.

#[non_exhaustive]

VerificationRejected

A post-update verification callback (verify_binary) rejected the freshly-extracted binary.

This is a user-controlled rejection: the caller’s verify_binary closure returned Err(..) (an explicit rejection or a hook IO error), so nothing was installed. reason carries the hook error’s message when one was returned (else None).

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

reason: Option<String>

The reason the verification was rejected — the hook error’s message, if any.

#[non_exhaustive]

ChecksumMismatch

The downloaded artifact’s checksum did not match the expected digest.

expected is the configured digest; computed is the one actually produced from the downloaded file. Both are hex-encoded lowercase digests.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

expected: String

The expected digest (from the configured Checksum), hex-encoded.

computed: String

The digest produced from the downloaded file, hex-encoded.

Aborted

The user declined the interactive confirmation prompt.

Returned when no_confirm is false (the default) and the user answers anything other than y / Y / Enter at the “Do you want to continue?” prompt.

#[non_exhaustive]

NotFound

A request completed and returned HTTP 404 (resource not found).

url is the request URL that produced the 404.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

url: String

The URL whose response was HTTP 404.

#[non_exhaustive]

Unauthorized

A request completed and returned HTTP 401 or 403 (not authorized).

status is the exact HTTP status code (401 or 403). url is the request URL.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

status: u16

The HTTP status code (401 or 403).

url: String

The URL whose response was this status.

#[non_exhaustive]

HttpStatus

A request completed and returned a non-2xx status other than 404, 401, or 403.

status is the HTTP status code. url is the request URL.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

status: u16

The HTTP status code.

url: String

The URL whose response was this status.

#[non_exhaustive]

NoReleaseFound

No release (or no release asset matching the requested target) was found.

This is the clean negative outcome of a release lookup: the remote listing had no release, no release matched the requested tag/version, or the resolved release had no asset for target. target is the requested target triple when the lookup was asset-scoped, else None.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

target: Option<String>

The requested target triple, when the lookup failed to find a matching asset; else None.

#[non_exhaustive]

MissingAssetField

A release or asset payload from the backend was missing a required field.

field is the name of the absent field (e.g. "tag_name", "browser_download_url"), or a path to it (e.g. "assets[2].url").

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

field: String

The name of (or path to) the missing field in the release/asset payload.

#[non_exhaustive]

InvalidResponse

A backend response could not be parsed.

Wraps the underlying parse error (e.g. an S3 XML reader error or a regex build failure), surfaced via std::error::Error::source.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Box<dyn Error + Send + Sync>

The underlying parse error.

#[non_exhaustive]

MissingField

A required builder/configuration field was not set.

field names the missing field (e.g. "repo_owner", "bin_name", "region").

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

field: &'static str

The name of the missing required field.

NoCurrentVersion

A bare release listing (ReleaseList::fetch) carries no current version, so Releases::is_update_available has nothing to compare its releases against.

Distinct from MissingField: there is no builder field to set. Use Update::is_update_available on a configured updater (which knows its current version) instead.

#[non_exhaustive]

InvalidHeader

An HTTP header supplied to the builder (request_header / header) was not valid.

Wraps the underlying header-conversion error, surfaced via std::error::Error::source.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Box<dyn Error + Send + Sync>

The underlying header-conversion error.

#[non_exhaustive]

InvalidAuthToken

An auth token could not be encoded as an HTTP Authorization header value.

Wraps the underlying header-conversion error, surfaced via std::error::Error::source.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Box<dyn Error + Send + Sync>

The underlying header-conversion error.

#[non_exhaustive]

InvalidCertificate

A custom TLS root certificate could not be parsed, or the HTTP client that would trust it could not be built.

Produced from build() (via a backend builder’s add_root_certificate) or from a Download with a root_certificate. Wraps the underlying error, surfaced via std::error::Error::source.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Box<dyn Error + Send + Sync>

The underlying certificate-parse / client-build error.

#[non_exhaustive]

InvalidProgressStyle

Available on crate feature progress-bar only.

A progress-bar template string was not valid (progress-bar).

Wraps the underlying indicatif template error, surfaced via std::error::Error::source.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

source: Box<dyn Error + Send + Sync>

The underlying template-parse error.

Io(Error)

A wrapper over a std::io::Error.

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

Available on crate feature archive-zip only.

A wrapper over a zip archive error (archive-zip).

The concrete error is boxed so that the public API does not change when the underlying zip implementation evolves. Use std::error::Error::source to inspect the underlying error.

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

A wrapper over a serde_json::Error.

The concrete error is boxed so that the public API does not change when the underlying serde_json implementation evolves. Use std::error::Error::source to inspect the underlying error.

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

The request could not be completed (connection/TLS/timeout/transport failure).

The concrete error is boxed so that the public API does not change when the reqwest / ureq feature selection changes. Use std::error::Error::source to inspect the underlying error.

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

A wrapper over a semver::Error.

The concrete error is boxed so that the public API does not change when the underlying semver implementation evolves. Use std::error::Error::source to inspect the underlying error.

ArchiveNotEnabled(String)

Used when the archive container feature (archive-tar / archive-zip) for the detected asset is not enabled. The string is the archive token ("tar" / "zip").

CompressionNotEnabled(String)

The asset is compressed with a codec whose feature is not enabled.

The string is the codec token ("gz"). Enable the matching feature (compression-tar-gz for gzip) to decode it. Distinct from ArchiveNotEnabled, which concerns the container format; without this, a gzip asset would install its still-compressed bytes as the binary.

NoSignatures(ArchiveKind)

Available on crate feature signatures only.

Used when the repository archive does not contain any signatures to verify with.

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

Available on crate feature signatures only.

A wrapper over a signature-verification error (signatures).

The concrete error is boxed so that the public API surface does not depend on the signing implementation’s internal error types. Use std::error::Error::source to inspect the underlying error.

#[non_exhaustive]

InvalidAssetName

The release asset name contains path traversal components or separators.

Returned when the server-supplied asset name is empty, is . or .., contains a / or \ path separator, or is an absolute path. The file would never be created in that case, so callers do not need to clean up temporary state.

Fields

Non-exhaustive enum variants could have additional fields added in future. Therefore, non-exhaustive enum variants cannot be constructed in external crates and cannot be matched against.

name: String

The offending asset name as received from the release listing.

SignatureNonUTF8

Available on crate feature signatures only.

Used when the path generated to store the repository archive contains non-UTF8 characters.

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

Available on crate feature s3-auth only.

A wrapper over the errors that can occur while signing S3 requests (s3-auth).

The concrete error is boxed so that the public API surface does not depend on the signing implementation’s internal error types. Use std::error::Error::source to inspect the underlying error.

Implementations

impl Error

pub fn http_status(&self) -> Option<u16>

The HTTP status code if this error came from a completed non-2xx response (NotFound => 404, Unauthorized/HttpStatus => their code); None otherwise.

pub fn url(&self) -> Option<&str>

The URL of the request that failed, for the HTTP error variants (NotFound/Unauthorized/HttpStatus); None otherwise.

pub fn no_release_found() -> Error

Construct a NoReleaseFound error: the listing had no release, or no release matched the requested tag/version. For a lookup that failed to find an asset for a specific target triple, use no_release_found_for_target.

pub fn no_release_found_for_target(target: impl Into<String>) -> Error

Construct a NoReleaseFound error for an asset-scoped lookup: a release was resolved but had no asset matching target.

pub fn missing_asset_field(field: impl Into<String>) -> Error

Construct a MissingAssetField error for a release/asset payload missing a required field. field names the absent field, or a path to it (e.g. format!("assets[{i}].url")).

pub fn checksum_mismatch( expected: impl Into<String>, computed: impl Into<String>, ) -> Error

Construct a ChecksumMismatch error from the expected and computed digests (both hex-encoded lowercase).

pub fn invalid_response( source: impl Into<Box<dyn Error + Send + Sync>>, ) -> Error

Construct an InvalidResponse error wrapping the underlying parse error.

pub fn http_status_error(status: u16, url: impl Into<String>) -> Error

Construct the HTTP status error for a completed non-2xx response: NotFound for 404, Unauthorized for 401/403, else HttpStatus.

pub fn verification_rejected(reason: impl Into<String>) -> Error

Construct a VerificationRejected error with the given reason, for rejecting the extracted binary from a verify_binary hook:

|path: &std::path::Path| {
    if check(path) {
        Ok(())
    } else {
        Err(self_update::Error::verification_rejected("new binary failed --version"))
    }
}

The update pipeline surfaces this error as-is; any other error returned from the hook is wrapped in a VerificationRejected whose reason is that error’s message.

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

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<ComponentRange> for Error

Available on crate feature s3-auth only.

fn from(e: ComponentRange) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(e: Error) -> Error

Converts to this type from the input type.

impl From<Error> for Error

fn from(e: Error) -> Error

Converts to this type from the input type.

impl From<Error> for Error

Available on crate feature reqwest only.

fn from(e: Error) -> Error

Converts to this type from the input type.

impl From<Error> for Error

Available on crate feature ureq only.

fn from(e: Error) -> Error

Converts to this type from the input type.

impl From<Error> for Error

fn from(e: Error) -> Error

Converts to this type from the input type.

impl From<InvalidLength> for Error

Available on crate feature s3-auth only.

fn from(e: InvalidLength) -> Self

Converts to this type from the input type.

impl From<ParseError> for Error

Available on crate feature s3-auth only.

fn from(e: ParseError) -> Self

Converts to this type from the input type.

impl From<SystemTimeError> for Error

Available on crate feature s3-auth only.

fn from(e: SystemTimeError) -> Self

Converts to this type from the input type.

impl From<ZipError> for Error

Available on crate feature archive-zip only.

fn from(e: ZipError) -> Error

Converts to this type from the input type.

impl From<ZipsignError> for Error

Available on crate feature signatures only.

fn from(e: ZipsignError) -> Error

Converts to this type from the input type.