Struct Message 

pub struct Message {
    pub message: Cow<'static, str>,
    pub class: Option<Class>,
    pub values: Metadata,
}

A diagnostic message with an optional semantic class and named diagnostic values.

Use this instead of chaining message, classification, and scalar-context errors when they describe a single failure. Self::new() starts without a class or values; Self::with_class() and Self::with() add them. Class builders such as Self::corrupted(), Self::validation(), Self::not_found(), Self::retryable(), and Self::resource_exhaustion() are useful with formatted crate::message!s. Self::allocation_limit() and Self::allocation_failure() select common resource exhaustion kinds. Builders ending in _error, such as Self::corrupted_error() and Self::validation_error(), also raise the classified message as an Error. Class-based constructors such as crate::not_found() combine the message and class in one step.

Unlike ClassificationMarker, this is a visible diagnostic: it participates in error iteration, downcasting, reports, and cause selection. A marker only adds a classification to an existing error without a diagnostic of its own, preserving that error’s concrete type. Both are inspected by crate::classify(). The class itself isn’t displayed, and crate::types::Classification::error() refers to this error, not a synthetic source.

Preserve real callee errors with ResultExt::or_raise() or Exn::raise(). Keep concrete error types when recovery requires a specific condition or payload; use classification predicates to recognize categories, and document diagnostic keys on the function returning them. Exn::metadata() and crate::Error::metadata() yield each message’s non-empty value dictionary. Use Exn::metadata_merged() or crate::Error::metadata_merged() to combine them, letting more specific causes override their enclosing contexts. To identify a specific failure, downcast to its operation’s error enum and match a variant; see matching a specific failure.

Debug formatting omits absent classes and empty values. Present classes omit their Some wrapper, and the class and values stay on single lines, even in pretty output.

Fields

message: Cow<'static, str>

The operation or situation described by these values.

class: Option<Class>

The semantic class of this diagnostic, if known.

values: Metadata

Diagnostic values, ordered by key. Functions returning metadata document their keys.

Implementations

impl Message

Lifecycle

pub fn new(message: impl Into<Cow<'static, str>>) -> Self

Create a diagnostic with message, no classification, and no values.

pub fn with_class(self, class: Class) -> Self

Set class, replacing any previous classification without adding a cause.

impl Message

Builders

pub fn corrupted(self) -> Self

Classify malformed or internally inconsistent stored or streamed data as Class::Corruption.

Like Self::with_class(), this replaces any previous class without changing the message or values or adding a cause.

pub fn corrupted_error(self) -> Error

Classify malformed or internally inconsistent stored or streamed data and raise it as an Error.

Like Self::corrupted(), this preserves the message and values and replaces any previous class without adding a cause. The error records the caller’s location, just like ErrorExt::raise().

pub fn validation(self) -> Self

Classify invalid function or method input as Class::Validation.

Like Self::with_class(), this replaces any previous class without changing the message or values or adding a cause.

pub fn validation_error(self) -> Error

Classify invalid function or method input and raise it as an Error.

Like Self::validation(), this preserves the message and values and replaces any previous class without adding a cause. The error records the caller’s location, just like ErrorExt::raise().

pub fn not_found(self) -> Self

Classify a missing resource as Class::NotFound.

Like Self::with_class(), this replaces any previous class without changing the message or values or adding a cause.

pub fn not_found_error(self) -> Error

Classify a missing resource and raise it as an Error.

Like Self::not_found(), this preserves the message and values and replaces any previous class without adding a cause. The error records the caller’s location, just like ErrorExt::raise().

pub fn retryable(self) -> Self

Classify an operation that may succeed when retried as Class::Retryable.

Like Self::with_class(), this replaces any previous class without changing the message or values or adding a cause.

pub fn retryable_error(self) -> Error

Classify an operation that may succeed when retried and raise it as an Error.

Like Self::retryable(), this preserves the message and values and replaces any previous class without adding a cause. The error records the caller’s location, just like ErrorExt::raise().

pub fn cancelled(self) -> Self

The caller requested cancellation; stop rather than retry.

Replaces any previous class without changing the message or values or adding a cause.

pub fn cancelled_error(self) -> Error

Apply Self::cancelled() and raise the message, recording the caller location.

pub fn permission_denied(self) -> Self

Authorization or permissions are insufficient; obtain authorization or change permissions.

Replaces any previous class without changing the message or values or adding a cause.

pub fn permission_denied_error(self) -> Error

Apply Self::permission_denied() and raise the message, recording the caller location.

pub fn unauthenticated(self) -> Self

Credentials are missing or rejected; obtain or refresh credentials.

Replaces any previous class without changing the message or values or adding a cause.

pub fn unauthenticated_error(self) -> Error

Apply Self::unauthenticated() and raise the message, recording the caller location.

pub fn conflict(self) -> Self

Current state conflicts with the operation; refresh or reconcile state before retrying.

Replaces any previous class without changing the message or values or adding a cause.

pub fn conflict_error(self) -> Error

Apply Self::conflict() and raise the message, recording the caller location.

pub fn unsupported(self) -> Self

A required capability is unsupported; switch implementation, format, protocol, or strategy.

Replaces any previous class without changing the message or values or adding a cause.

pub fn unsupported_error(self) -> Error

Apply Self::unsupported() and raise the message, recording the caller location.

pub fn resource_exhaustion(self, kind: ResourceExhaustionKind) -> Self

Classify an exhausted resource as Class::ResourceExhaustion of kind.

Like Self::with_class(), this replaces any previous class without changing the message or values or adding a cause.

pub fn resource_exhaustion_error(self, kind: ResourceExhaustionKind) -> Error

Classify an exhausted resource of kind and raise it as an Error.

Like Self::resource_exhaustion(), this preserves the message and values and replaces any previous class without adding a cause. The error records the caller’s location, just like ErrorExt::raise().

pub fn allocation_limit(self) -> Self

Classify an exceeded application-configured allocation limit.

Like Self::resource_exhaustion(), this preserves the message and values and replaces any previous class without adding a cause.

pub fn allocation_limit_error(self) -> Error

Classify an exceeded application-configured allocation limit and raise it as an Error.

Like Self::allocation_limit(), this preserves the message and values and replaces any previous class without adding a cause. The error records the caller’s location, just like ErrorExt::raise().

pub fn allocation_failure(self) -> Self

Classify an unrepresentable allocation size or memory that could not be reserved.

Like Self::resource_exhaustion(), this preserves the message and values and replaces any previous class without adding a cause.

pub fn allocation_failure_error(self) -> Error

Classify an unrepresentable allocation size or memory that could not be reserved and raise it as an Error.

Like Self::allocation_failure(), this preserves the message and values and replaces any previous class without adding a cause. The error records the caller’s location, just like ErrorExt::raise().

impl Message

Metadata builders

pub fn with_input(self, input: impl Into<MetadataValue>) -> Self

Record the offending input using the input validation schema.

Replaces input in this context, preserving its representation through MetadataValue. Other values, the message, and the classification are unchanged; input does not imply Class::Validation. Only record already-known input that is appropriate for diagnostics, never secrets or other sensitive data.

pub fn with_command_status(self, command: &Command, status: ExitStatus) -> Self

Record a command’s program and exit status using the external program runtime failure schema.

Replaces program with the native program name or path from std::process::Command::get_program(), without resolving it, and exit_status with the status’s display representation. Sets exit_code when available, otherwise removes any previous exit_code. Other values, the message, and the classification are unchanged. This does not require a failed status or imply a recovery class, and does not capture output.

pub fn with_program(self, program: impl AsRef<OsStr>) -> Self

Record an already-known program name or path as program, without resolving it or changing the classification.

Use std::process::Command::get_program() when a prepared command is available.

pub fn with_exit_status(self, status: ExitStatus) -> Self

Record exit_status and an available exit_code using the external program runtime failure schema.

Replaces any previous status and removes a previous exit_code if this status has none. Does not require a failed status, change the classification, or collect program identity or output.

pub fn with_command_output(self, command: &Command, output: Output) -> Self

Record a command’s program, exit status, and already-captured output using the external program runtime failure schema.

Like Self::with_command_status(), replaces the program and status fields, then replaces stdout and stderr with the captured bytes, including empty buffers. Does not execute a command or capture more output. Only use this when both streams are appropriate for diagnostics; in particular, do not record credential output.

pub fn with( self, key: impl Into<Cow<'static, str>>, value: impl Into<MetadataValue>, ) -> Self

Add value under key, replacing any previous value in this context. Inspect values through crate::Error::metadata(), or crate::Exn::metadata() on typed exceptions.

Trait Implementations

impl Debug for Message

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

Formats the value using the given formatter.

impl Display for Message

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

Formats the value using the given formatter.

impl Error for Message

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<&'static str> for Message

fn from(message: &'static str) -> Self

Converts to this type from the input type.

impl From<Cow<'static, str>> for Message

fn from(message: Cow<'static, str>) -> Self

Converts to this type from the input type.

impl From<Message> for Error

fn from(err: Message) -> Self

Raise the message at the caller’s location, including when converted with .into() or ?. When used as a function pointer, caller tracking stops at the pointer’s invocation shim; use a closure such as |message| message.raise() to capture a location in the calling code.

impl From<String> for Message

fn from(message: String) -> Self

Converts to this type from the input type.