Enum Error 

pub enum Error {
    Io(Error),
    Config(String),
    Control(Error),
    State(String),
    Consensus(String),
    NoNodesRemain,
    Validation(String),
    DescriptorUnavailable(String),
}

Errors that can occur during vanguards-rs operations.

This enum represents all possible error conditions in the library. Each variant provides specific information about the failure and guidance on recovery.

Error Handling Patterns

Match on Specific Errors

use vanguards_rs::Error;

fn handle_error(err: Error) {
    match err {
        Error::Io(io_err) => {
            eprintln!("I/O error: {}", io_err);
            // Check file permissions, disk space, network
        }
        Error::Config(msg) => {
            eprintln!("Configuration error: {}", msg);
            // Fix configuration and restart
        }
        Error::Control(ctrl_err) => {
            eprintln!("Tor control error: {}", ctrl_err);
            // Reconnect to Tor
        }
        Error::State(msg) => {
            eprintln!("State file error: {}", msg);
            // Delete state file and restart
        }
        Error::Consensus(msg) => {
            eprintln!("Consensus error: {}", msg);
            // Wait for Tor to get new consensus
        }
        Error::NoNodesRemain => {
            eprintln!("No nodes remain after filtering");
            // Adjust ExcludeNodes configuration
        }
        Error::Validation(msg) => {
            eprintln!("Validation error: {}", msg);
            // Fix invalid input
        }
        Error::DescriptorUnavailable(msg) => {
            eprintln!("Descriptor unavailable: {}", msg);
            // Wait for Tor to finish bootstrapping
        }
    }
}

Check if Retryable

use vanguards_rs::Error;

fn is_retryable(err: &Error) -> bool {
    matches!(err,
        Error::Io(_) |
        Error::Control(_) |
        Error::Consensus(_) |
        Error::DescriptorUnavailable(_)
    )
}

See Also

• Result - Type alias using this error type
• [stem_rs::Error] - Underlying control protocol errors

Variants

Io(Error)

I/O error during file or network operations.

This error wraps standard I/O errors that occur during file operations (reading/writing state files, config files) or network operations.

Recovery

• Check file permissions and paths
• Retry with exponential backoff for transient issues
• Verify disk space for write operations

Config(String)

Configuration error.

This error indicates invalid configuration values or parsing failures. The message describes what was wrong with the configuration.

Recovery

Fix the configuration file or command-line arguments. This error is not recoverable without user intervention.

Control(Error)

Tor control protocol error.

This error wraps errors from stem-rs when communicating with Tor’s control port.

Recovery

• Check if Tor is running
• Verify control port configuration
• Retry connection with backoff

State(String)

State file error.

This error indicates problems with the vanguard state file, such as corruption, invalid format, or incompatible version.

Recovery

• Delete the corrupted state file and let vanguards create a fresh one
• Check file permissions
• Verify the file wasn’t modified externally

Consensus(String)

Consensus parsing error.

This error occurs when parsing the network consensus fails.

Recovery

• Wait for a new consensus
• Verify Tor has finished bootstrapping
• Check DataDirectory configuration

NoNodesRemain

No nodes remain after applying restrictions.

This error occurs when all relays are filtered out by the configured restrictions (ExcludeNodes, flag requirements, etc.).

Recovery

• Review ExcludeNodes configuration
• Reduce restrictions
• Wait for more relays to appear in consensus

Validation(String)

Input validation error.

This error indicates that input data failed validation checks.

Recovery

Fix the invalid input. This error is not recoverable without correcting the input data.

DescriptorUnavailable(String)

Descriptor unavailable.

This error occurs when Tor doesn’t have the required descriptors cached yet, typically during bootstrap.

Recovery

• Wait for Tor to finish bootstrapping
• Retry after a short delay

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, __formatter: &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<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.

impl From<Error> for Error

fn from(source: Error) -> Self

Converts to this type from the input type.