Struct Error

pub struct Error {
    pub profile: Option<Profile>,
    pub metadata: Option<Metadata>,
    pub path: Vec<String>,
    pub kind: Kind,
    /* private fields */
}

An error that occured while producing data or extracting a configuration.

Constructing Errors

An Error will generally be constructed indirectly via its implementations of serde’s de::Error and ser::Error, that is, as a result of serialization or deserialization errors. When implementing Provider, however, it may be necessary to construct an Error directly.

Broadly, there are two ways to construct an Error:

• With an error message, as Error impls From<String> and From<&str>:

  use figment::Error;
  
  Error::from(format!("{} is invalid", 1));
  
  Error::from("whoops, something went wrong!");

• With a Kind, as Error impls From<Kind>:

  use figment::{error::{Error, Kind}, value::Value};
  
  let value = Value::serialize(&100).unwrap();
  if !value.as_str().is_some() {
      let kind = Kind::InvalidType(value.to_actual(), "string".into());
      let error = Error::from(kind);
  }

As always, ? can be used to automatically convert into an Error using the available From implementations:

use std::fs::File;

fn try_read() -> Result<(), figment::Error> {
    let x = File::open("/tmp/foo.boo").map_err(|e| e.to_string())?;
    Ok(())
}

Display

By default, Error uses all of the available information about the error, including the Metadata, path, and profile to display a message that resembles the following, where $ is error. for some error: Error:

$kind: `$metadata.interpolate($path)` in $($metadata.sources())*

Concretely, such an error may look like:

invalid type: found sequence, expected u16: `staging.port` in TOML file Config.toml

Iterator

An Error may contain more than one error. To process all errors, iterate over an Error:

fn with_error(error: figment::Error) {
    for error in error {
        println!("error: {}", error);
    }
}

Fields

profile: Option<Profile>

The profile that was selected when the error occured, if any.

metadata: Option<Metadata>

The metadata for the provider of the value that errored, if known.

path: Vec<String>

The path to the configuration key that errored, if known.

kind: Kind

The error kind.

Implementations

impl Error

pub fn missing(&self) -> bool

Returns true if the error’s kind is MissingField.

Example

use figment::error::{Error, Kind};

let error = Error::from(Kind::MissingField("path".into()));
assert!(error.missing());

pub fn with_path(self, path: &str) -> Error

Append the string path to the error’s path.

Example

use figment::Error;

let error = Error::from("an error message").with_path("some_path");
assert_eq!(error.path, vec!["some_path"]);

let error = Error::from("an error message").with_path("some.path");
assert_eq!(error.path, vec!["some", "path"]);

pub fn chain(self, error: Error) -> Error

Prepends self to error and returns error.

use figment::error::Error;

let e1 = Error::from("1");
let e2 = Error::from("2");
let e3 = Error::from("3");

let error = e1.chain(e2).chain(e3);
assert_eq!(error.count(), 3);

let unchained = error.into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>();
assert_eq!(unchained, vec!["3", "2", "1"]);

let e1 = Error::from("1");
let e2 = Error::from("2");
let e3 = Error::from("3");
let error = e3.chain(e2).chain(e1);
assert_eq!(error.count(), 3);

let unchained = error.into_iter()
    .map(|e| e.to_string())
    .collect::<Vec<_>>();
assert_eq!(unchained, vec!["1", "2", "3"]);

pub fn count(&self) -> usize

Returns the number of errors represented by self.

Example

use figment::{Figment, providers::{Format, Toml}};

figment::Jail::expect_with(|jail| {
    jail.create_file("Base.toml", r#"
        cat = [1
    "#)?;

    jail.create_file("Release.toml", r#"
        cat = "
    "#)?;

    let figment = Figment::from(Toml::file("Base.toml"))
        .merge(Toml::file("Release.toml"));

    let error = figment.extract_inner::<String>("cat").unwrap_err();
    assert_eq!(error.count(), 2);

    Ok(())
});

Trait Implementations

impl Clone for Error

fn clone(&self) -> Error

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

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

Formats the value using the given formatter.

impl Error for Error

fn custom<T>(msg: T) -> Error

where T: Display,

Raised when there is general error when deserializing a type.

fn invalid_type(unexp: Unexpected<'_>, exp: &dyn Expected) -> Error

Raised when a Deserialize receives a type different from what it was expecting.

fn invalid_value(unexp: Unexpected<'_>, exp: &dyn Expected) -> Error

Raised when a Deserialize receives a value of the right type but that is wrong for some other reason.

fn invalid_length(len: usize, exp: &dyn Expected) -> Error

Raised when deserializing a sequence or map and the input data contains too many or too few elements.

fn unknown_variant(variant: &str, expected: &'static [&'static str]) -> Error

Raised when a Deserialize enum type received a variant with an unrecognized name.

fn unknown_field(field: &str, expected: &'static [&'static str]) -> Error

Raised when a Deserialize struct type received a field with an unrecognized name.

fn missing_field(field: &'static str) -> Error

Raised when a Deserialize struct type expected to receive a required field with a particular name but that field was not present in the input.

fn duplicate_field(field: &'static str) -> Error

Raised when a Deserialize struct type received more than one of the same field.

impl Error for Error

fn custom<T>(msg: T) -> Error

where T: Display,

Used when a Serialize implementation encounters any error while serializing a type.

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<&str> for Error

fn from(string: &str) -> Error

Converts to this type from the input type.

impl<A, B> From<Error> for Error<A, B>

fn from(e: Error) -> Self

Converts to this type from the input type.

impl From<Kind> for Error

fn from(kind: Kind) -> Error

Converts to this type from the input type.

impl From<String> for Error

fn from(string: String) -> Error

Converts to this type from the input type.

impl IntoIterator for Error

type Item = Error

The type of the elements being iterated over.

type IntoIter = IntoIter

Which kind of iterator are we turning this into?

fn into_iter(self) -> <Error as IntoIterator>::IntoIter

Creates an iterator from a value.

impl PartialEq for Error

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

Tests for self and other values to be equal, and is used by ==.

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

Tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl StructuralPartialEq for Error