pub enum Error {
Show 15 variants
Socket(Error),
Protocol(String),
Authentication(AuthError),
OperationFailed {
code: String,
message: String,
},
UnsatisfiableRequest(String),
InvalidRequest(String),
InvalidArguments(String),
Parse {
location: String,
reason: String,
},
Download {
url: String,
reason: String,
},
DownloadTimeout {
url: String,
},
Timeout,
SocketClosed,
DescriptorUnavailable(String),
CircuitExtensionFailed(String),
AddrParse(AddrParseError),
}Expand description
Errors that can occur during stem-rs operations.
This enum represents all possible error conditions in the library. Each variant provides specific information about the failure.
§Error Categories
- I/O Errors:
Socket- Connection and communication failures - Protocol Errors:
Protocol- Malformed control protocol data - Auth Errors:
Authentication- Authentication failures - Operation Errors:
OperationFailed- Tor rejected the request - Parse Errors:
Parse- Descriptor parsing failures
§Recovery Guide
| Error | Recoverable | Retry Meaningful |
|---|---|---|
Socket | Sometimes | Yes, with backoff |
Protocol | No | No |
Authentication | Sometimes | Yes, with different credentials |
OperationFailed | Depends on code | Check error code |
Parse | No | No |
Timeout | Yes | Yes, with longer timeout |
SocketClosed | Yes | Yes, reconnect first |
Download | Sometimes | Yes, with backoff |
DownloadTimeout | Yes | Yes, with longer timeout |
§Example
use stem_rs::Error;
fn handle_error(err: Error) {
match err {
Error::Socket(io_err) => {
eprintln!("Connection failed: {}", io_err);
// Retry with exponential backoff
}
Error::Authentication(auth_err) => {
eprintln!("Auth failed: {}", auth_err);
// Check credentials or try different auth method
}
Error::Parse { location, reason } => {
eprintln!("Parse error at {}: {}", location, reason);
// Log and skip this descriptor
}
Error::OperationFailed { code, message } => {
eprintln!("Tor rejected request: {} - {}", code, message);
// Check if operation can be retried
}
_ => eprintln!("Error: {}", err),
}
}Variants§
Socket(Error)
I/O error during socket communication.
This error wraps standard I/O errors that occur during socket operations. Common causes include connection refused, connection reset, and network unreachable errors.
§Recovery
- Check if Tor is running and the control port is accessible
- Retry with exponential backoff for transient network issues
- Verify firewall rules allow the connection
Protocol(String)
Malformed data received from the control protocol.
This indicates the data received from Tor doesn’t conform to the expected control protocol format. This typically indicates a bug in either Tor or this library.
§Recovery
This error is not recoverable. Report the issue with the malformed data.
Authentication(AuthError)
Authentication with Tor failed.
See AuthError for specific authentication failure reasons.
§Recovery
- Check credentials (password, cookie file path)
- Verify Tor’s authentication configuration
- Try a different authentication method
OperationFailed
Tor was unable to complete the requested operation.
This error is returned when Tor understands the request but cannot fulfill it. The error code and message provide details about why.
§Fields
code: The numeric error code from Tor (e.g., “552”)message: Human-readable error description from Tor
§Recovery
Check the error code to determine if retry is meaningful:
- 4xx codes: Client error, fix the request
- 5xx codes: Server error, may be transient
Fields
UnsatisfiableRequest(String)
The request cannot be satisfied with current Tor state.
This error indicates a valid request that Tor cannot fulfill due to its current state (e.g., requesting a circuit when Tor is not connected).
§Recovery
Wait for Tor to reach the required state, then retry.
InvalidRequest(String)
The request was malformed or invalid.
This indicates a programming error - the request doesn’t conform to the control protocol specification.
§Recovery
Fix the request format. This is not a transient error.
InvalidArguments(String)
The request contained invalid arguments.
Similar to InvalidRequest, but specifically
for argument validation failures.
§Recovery
Fix the arguments. This is not a transient error.
Parse
Failed to parse a descriptor or other structured data.
This error occurs when parsing Tor descriptors (server descriptors, consensus documents, etc.) and the data doesn’t match the expected format.
§Fields
location: Where in the data the parse error occurredreason: Description of what was expected vs. found
§Recovery
This error is not recoverable for the specific descriptor. Log the error and skip to the next descriptor if processing multiple.
Fields
Download
Failed to download a resource from the network.
This error occurs when downloading descriptors or other data from directory authorities or mirrors.
§Fields
url: The URL that failed to downloadreason: Description of the failure
§Recovery
- Retry with exponential backoff
- Try a different directory authority or mirror
Fields
DownloadTimeout
Download timed out before completing.
The configured timeout was reached before the download completed.
§Recovery
- Increase the timeout value
- Try a different server
- Check network connectivity
Timeout
A general operation timeout occurred.
The operation did not complete within the expected time.
§Recovery
- Increase timeout if configurable
- Check if Tor is responsive
- Retry the operation
SocketClosed
The control socket was closed unexpectedly.
This indicates the connection to Tor was lost. This can happen if Tor exits, the network connection is interrupted, or the socket is closed from the other end.
§Recovery
Reconnect to Tor and re-authenticate.
The requested descriptor is not available.
Tor doesn’t have the requested descriptor cached and cannot retrieve it.
§Recovery
- Wait and retry (descriptor may become available)
- Try downloading from a different source
CircuitExtensionFailed(String)
Failed to extend or create a circuit.
The circuit could not be built through the requested relays.
§Recovery
- Try different relays
- Wait for network conditions to improve
- Check if the target relay is online
AddrParse(AddrParseError)
Failed to parse a socket address.
This error occurs when parsing a string into a socket address fails.
§Recovery
Verify the address format is correct (e.g., “127.0.0.1:9051”).