Skip to main content

ErrorDetail

Enum ErrorDetail 

Source
#[non_exhaustive]
pub enum ErrorDetail {
Show 65 variants Empty { subject: Subject, }, TooLong { subject: Subject, limit: usize, }, Invalid { subject: Subject, value: String, }, ControlCharacters { subject: Subject, }, NotVisibleAscii { subject: Subject, }, ContainsWhitespace { subject: Subject, value: String, }, MustBeAtLeastOneSecond { subject: Subject, source: ValueSource, }, AboveHardMaximum { subject: Subject, hard_max: u64, source: ValueSource, }, ItemPathNoSegments, ItemPathMissingItemName, CrateRefMultipleAt, CrateRefEmptyName, CrateRefEmptyVersion, VersionBuildMetadata, VersionVPrefix, UnknownMatchMode { value: String, }, UnknownItemType { value: String, }, UnsupportedLang { tag: String, }, UnknownSchemaCommand { value: String, }, JsonFormatConflict, ClapUsage { message: String, }, InvalidFilterExpression { expr: String, reason: String, }, ModuleFilterUnsupported, AmbientTargetRefused { verb: String, target: String, target_flag: String, waiver_flag: String, effect: DestructiveEffect, }, PageBelowOne, PerPageOutOfRange { max: u32, got: u32, }, OriginBadScheme { scheme: String, }, OriginMissingHost { url: String, }, OriginNotAllowlisted { host: String, allowed: String, }, ItemPathSegmentCharset { segment: String, }, ConflictingVersions { from_ref: String, from_flag: String, }, ConfigDirUnresolved, CacheDirUnresolved, ConfigTomlInvalid, ConfigTomlNotUtf8, ConfigAlreadyExists { path: String, }, ConfigTomlTooLarge { max_bytes: u64, }, UserAgentHeaderInvalid, HttpStatus { status: u16, hint: String, }, HostNotAllowlisted { host: String, stage: AllowlistStage, }, HttpRequestFailed { url: String, kind: ErrorKind, }, RedirectLimitExceeded, HttpClientBuild, BodyRead, BodyOverBudget { max_bytes: u64, }, CachedBodyOverBudget { max_bytes: u64, }, BodyReserveFailed { bytes: usize, }, BodyNotUtf8, UnexpectedContentType { expected: ContentKind, got: String, }, OutputOverBudget, HtmlToMarkdown, CratesIoJson, AssocParentPageNotFound, AssocAnchorMissing { anchors: String, }, AssocAnchorEmpty { anchor_id: String, }, MemberKindNeedsParent { kind: &'static str, member: String, parent_kinds: String, }, HitJoinFailed, HitBaseInvalid, Interrupted, Terminated, BrokenPipe, WallClockTimeout { secs: u64, }, Io { op: IoOp, path: Option<String>, cause: IoCause, }, Internal { op: InternalOp, }, WithSuggestions { base: Box<ErrorDetail>, suggestions: Vec<Suggestion>, },
}
Expand description

Every failure the product can report, as data.

Construct errors through super::AppError::of so the ErrorKind and the English wire message are both derived from one place.

Variants (Non-exhaustive)§

This enum is marked as 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.
§

Empty

subject was empty or blank.

Fields

§subject: Subject

What was empty.

§

TooLong

subject was longer than limit characters.

Fields

§subject: Subject

What was too long.

§limit: usize

Maximum accepted length in characters.

§

Invalid

subject did not satisfy its format rule.

Fields

§subject: Subject

What was invalid.

§value: String

The offending value, echoed back so the caller can see it.

§

ControlCharacters

subject contained control or invisible characters.

Fields

§subject: Subject

What carried the characters.

§

NotVisibleAscii

subject must be printable ASCII only.

Fields

§subject: Subject

What must be ASCII.

§

ContainsWhitespace

subject contained whitespace where none is allowed.

Fields

§subject: Subject

What carried the whitespace.

§value: String

The offending value.

§

MustBeAtLeastOneSecond

A duration knob was set to zero.

Fields

§subject: Subject

Which duration.

§source: ValueSource

Layer the value came from (decides invalid_input vs config).

§

AboveHardMaximum

A byte budget was raised above the product’s hard ceiling.

Fields

§subject: Subject

Which budget.

§hard_max: u64

The ceiling that cannot be raised.

§source: ValueSource

Layer the value came from (decides invalid_input vs config).

§

ItemPathNoSegments

An item path yielded no usable segments.

§

ItemPathMissingItemName

A non-module item path ended without an item name.

§

CrateRefMultipleAt

A crate reference carried more than one @.

§

CrateRefEmptyName

A crate reference had nothing before its @.

§

CrateRefEmptyVersion

A crate reference had nothing after its @.

§

VersionBuildMetadata

A version carried +build metadata, which docs.rs does not resolve.

§

VersionVPrefix

A version was written with the v prefix.

§

UnknownMatchMode

--match received a value outside the accepted set.

Fields

§value: String

What was passed.

§

UnknownItemType

A kind alias was not recognized.

Fields

§value: String

What was passed.

§

UnsupportedLang

--lang received an unsupported BCP-47 tag.

Fields

§tag: String

What was passed.

§

UnknownSchemaCommand

schema --cmd named a document that does not exist.

Fields

§value: String

What was passed.

§

JsonFormatConflict

--json was combined with a human output format.

§

ClapUsage

Argv failed clap parsing.

The text is clap’s own rendering, not ours, so it is carried verbatim and not translated — inventing a pt-BR version of someone else’s usage help would drift from what --help actually prints.

Fields

§message: String

clap’s rendered message.

§

InvalidFilterExpression

--filter could not be parsed.

Fields

§expr: String

The expression as written.

§reason: String

Why it was rejected.

§

ModuleFilterUnsupported

search-in-crate --item-type module has no catalogue to read.

§

AmbientTargetRefused

A destructive verb resolved its target from ambient state, not from argv.

This is the confused-deputy shape: the caller names the verb, the environment names the victim, and the two are never compared. Refusing here costs one flag; not refusing costs whichever cache root the process happened to resolve.

Fields

§verb: String

The invocation that was refused, in wire spelling.

§target: String

The target the environment resolved, so the caller sees the victim.

§target_flag: String

The flag that names the target in argv instead.

§waiver_flag: String

The flag that explicitly accepts the ambient target.

§effect: DestructiveEffect

What would have happened to the target.

Carried as data because the harm differs by verb: the first version of this message said “would delete” for every caller, which was simply false once a verb that overwrites started using it.

§

PageBelowOne

--page was zero or absent where one is required.

§

PerPageOutOfRange

--per-page fell outside its accepted range.

Fields

§max: u32

Highest accepted value.

§got: u32

What was passed.

§

OriginBadScheme

An origin URL used a scheme other than http or https.

Fields

§scheme: String

The scheme as written.

§

OriginMissingHost

An origin URL carried no host component.

Fields

§url: String

The URL as written.

§

OriginNotAllowlisted

An origin host was outside the SSRF allowlist.

Fields

§host: String

The rejected host.

§allowed: String

Comma-separated allowlist, so the operator sees the accepted set.

§

ItemPathSegmentCharset

An item path segment used characters outside the accepted set.

Fields

§segment: String

The offending segment.

§

ConflictingVersions

crate@version and --crate-version disagreed.

Fields

§from_ref: String

Version taken from the crate@version sugar.

§from_flag: String

Version taken from the explicit flag.

§

ConfigDirUnresolved

The XDG config directory could not be resolved.

§

CacheDirUnresolved

The XDG cache directory could not be resolved.

§

ConfigTomlInvalid

config.toml failed to parse as TOML.

§

ConfigTomlNotUtf8

config.toml was not valid UTF-8.

§

ConfigAlreadyExists

config init found an existing file and --force was absent.

Fields

§path: String

Absolute path that would have been overwritten.

§

ConfigTomlTooLarge

config.toml was larger than the read cap.

Fields

§max_bytes: u64

The cap in bytes.

§

UserAgentHeaderInvalid

The configured User-Agent was rejected as an HTTP header value.

§

HttpStatus

A remote returned a status that maps to a domain failure.

Fields

§status: u16

The HTTP status code.

§hint: String

Short non-sensitive context label (endpoint name, never a body).

§

HostNotAllowlisted

A request or redirect targeted a host outside the allowlist.

Fields

§host: String

The rejected host.

§stage: AllowlistStage

Which stage rejected it, so the operator knows where to look.

§

HttpRequestFailed

The transport failed before any status was seen.

Carries its own ErrorKind because the classification comes from reqwest (timeout vs connect vs body), not from the shape of the call.

Fields

§url: String

The URL that was being fetched.

§kind: ErrorKind

Classification supplied by the transport layer.

§

RedirectLimitExceeded

The redirect chain went past max_redirects.

§

HttpClientBuild

Building the HTTP client failed.

§

BodyRead

Reading the response body failed mid-stream.

§

BodyOverBudget

The response body passed the configured byte budget.

Fields

§max_bytes: u64

The budget in bytes.

§

CachedBodyOverBudget

A cached body no longer fits the current byte budget.

Fields

§max_bytes: u64

The budget in bytes.

§

BodyReserveFailed

Reserving body capacity failed (allocation refused).

Fields

§bytes: usize

Bytes that could not be reserved.

§

BodyNotUtf8

The response body was not valid UTF-8.

§

UnexpectedContentType

The response advertised a content type the endpoint cannot use.

Fields

§expected: ContentKind

Flavour the caller required.

§got: String

What the remote advertised.

§

OutputOverBudget

The emitted payload passed max_output_bytes.

§

HtmlToMarkdown

HTML could not be converted to Markdown.

§

CratesIoJson

crates.io returned JSON the parser rejected.

§

AssocParentPageNotFound

No parent page existed for an associated item.

§

AssocAnchorMissing

The parent page was found but carried no anchor for the member.

The rendered text must keep the sentinel prefix, since both the live probe and the recovery path match on it to stop walking parent kinds.

Fields

§anchors: String

Comma-separated anchor ids that were tried.

§

AssocAnchorEmpty

The member anchor existed but its docblock was empty.

Fields

§anchor_id: String

The anchor id that was found.

§

MemberKindNeedsParent

A member-only kind was requested without a parent to anchor against.

Fields

§kind: &'static str

The kind as the user typed it.

§member: String

The leaf they supplied, echoed into the suggested rewrite.

§parent_kinds: String

Comma-separated parent kinds that can host this member.

§

HitJoinFailed

A hit href could not be joined against its origin.

§

HitBaseInvalid

A hit’s source_url was not a usable join base.

§

Interrupted

SIGINT / Ctrl-C.

§

Terminated

SIGTERM.

§

BrokenPipe

stdout was closed by the reader.

§

WallClockTimeout

The wall-clock deadline elapsed.

Fields

§secs: u64

Deadline in seconds.

§

Io

A filesystem operation failed; the cause is on the source chain.

Build this with Self::io rather than by hand: the constructor is what classifies the OS cause while the std::io::Error is still available, and a hand-written cause is a guess about a value the caller already had.

Fields

§op: IoOp

What was being attempted.

§path: Option<String>

Path involved, when one is known and safe to show.

§cause: IoCause

Whether waiting could plausibly change the outcome.

§

Internal

An internal invariant or host facility failed.

Fields

§op: InternalOp

What was being attempted.

§

WithSuggestions

Another failure, with ranked --suggest alternatives appended.

Fields

§base: Box<ErrorDetail>

The failure being explained.

§suggestions: Vec<Suggestion>

Ranked alternatives, best first.

Implementations§

Source§

impl ErrorDetail

Source

pub fn kind(&self) -> ErrorKind

Canonical ErrorKind for this failure.

Derived here rather than passed by the caller so one detail can never be reported as two different kinds from two different call sites.

Source

pub fn io(op: IoOp, path: Option<String>, err: &Error) -> Self

Build a filesystem failure, classifying the OS cause at the call site.

The classification has to happen here because this is the last place the std::io::Error exists. One layer up there is only an ErrorKind, and ENOSPC and EACCES share it while deserving opposite answers.

Source

pub fn retryable(&self) -> bool

Whether an agent may retry the invocation that produced this failure.

Every kind but crate::error::ErrorKind::Io answers from the kind alone. Filesystem failure is the one case where two opposite answers share a kind, so the cause captured at construction wins.

Trait Implementations§

Source§

impl Clone for ErrorDetail

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source. Read more
Source§

impl Debug for ErrorDetail

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Eq for ErrorDetail

Source§

impl PartialEq for ErrorDetail

Source§

fn eq(&self, other: &Self) -> bool

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for ErrorDetail

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Checks if this value is equivalent to the given key. Read more
Source§

impl<Q, K> Equivalent<K> for Q
where Q: Eq + ?Sized, K: Borrow<Q> + ?Sized,

Source§

fn equivalent(&self, key: &K) -> bool

Compare self to key and return true if they are equal.
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T> Instrument for T

Source§

fn instrument(self, span: Span) -> Instrumented<Self> ⓘ

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more
Source§

fn in_current_span(self) -> Instrumented<Self> ⓘ

Instruments this type with the current Span, returning an Instrumented wrapper. Read more
Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> PolicyExt for T
where T: ?Sized,

Source§

fn and<P, B, E>(self, other: P) -> And<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more
Source§

fn or<P, B, E>(self, other: P) -> Or<T, P>
where T: Sized + Policy<B, E>, P: Policy<B, E>,

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more
Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
Source§

impl<T> WithSubscriber for T

Source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self> ⓘ
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
Source§

fn with_current_subscriber(self) -> WithDispatch<Self> ⓘ

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more