Enum Error 

pub enum Error {
    Send {
        identity: Identity,
        details: String,
    },
    Receive {
        identity: Identity,
        details: String,
    },
    Timeout {
        identity: Identity,
        timeout: Duration,
        operation: String,
    },
    Downcast {
        identity: Identity,
        expected_type: String,
    },
    Runtime {
        identity: Identity,
        details: String,
    },
    MailboxCapacity {
        message: String,
    },
    Join {
        identity: Identity,
        source: JoinError,
    },
}

Represents errors that can occur in the rsactor framework.

These errors may be encountered during various actor operations, such as sending messages with tell or ask, or during actor lifecycle operations like spawn.

Variants

Send

Error when sending a message to an actor

Fields

identity: Identity

ID of the actor that failed to receive the message

details: String

Additional context about the error

Receive

Error when receiving a response from an actor

Fields

identity: Identity

ID of the actor that failed to send a response

details: String

Additional context about the error

Timeout

Error when a request times out

Fields

identity: Identity

ID of the actor that timed out

timeout: Duration

The duration after which the request timed out

operation: String

Type of operation that timed out (e.g., “send”, “ask”)

Downcast

Error when downcasting a reply to the expected type

Fields

identity: Identity

ID of the actor that sent the incompatible reply

expected_type: String

The expected type name that the downcast failed to match

Runtime

Error when a runtime operation fails

Fields

identity: Identity

ID of the actor where the runtime error occurred

details: String

Additional context about the error

MailboxCapacity

Error related to mailbox capacity configuration

Fields

message: String

Detailed error message describing the mailbox capacity issue

Join

Error when awaiting a JoinHandle fails

Fields

identity: Identity

ID of the actor that spawned the task

source: JoinError

The original JoinError from tokio

Implementations

impl Error

pub fn is_retryable(&self) -> bool

Returns whether this error might succeed if retried.

⚠️ Important Caveat

This method checks the error type only and does not account for elapsed time. If you store an error instance and check is_retryable() later, it will still return true for Timeout errors even if significant time has passed.

Best Practice: Always use fresh error instances for retry decisions. Do not cache error instances for later retry logic.

Retryable Errors

Error Type	Retryable	Reason
Timeout	✓ Yes	Transient; may succeed with longer timeout
Send	✗ No	Actor stopped; channel permanently closed
Receive	✗ No	Reply channel dropped; cannot recover
Downcast	✗ No	Type mismatch; programming error
Runtime	✗ No	Actor lifecycle failure
MailboxCapacity	✗ No	Configuration error
Join	✗ No	Task panic or cancellation

Example

use rsactor::{ActorRef, Actor, Error, Message};
use std::time::Duration;

async fn send_with_retry<T, M>(
    actor: &ActorRef<T>,
    msg: M,
    max_attempts: usize,
) -> Result<(), Error>
where
    T: Actor + Message<M>,
    M: Clone + Send + 'static,
{
    let mut attempts = 0;
    loop {
        // Always get a fresh error from the current attempt
        match actor.tell(msg.clone()).await {
            Ok(()) => return Ok(()),
            Err(e) if e.is_retryable() && attempts < max_attempts => {
                attempts += 1;
                tokio::time::sleep(Duration::from_millis(100 * attempts as u64)).await;
            }
            Err(e) => return Err(e),
        }
    }
}

pub fn debugging_tips(&self) -> &'static [&'static str]

Returns actionable debugging tips for this error.

Example

use rsactor::Error;

fn log_error(err: &Error) {
    eprintln!("Error: {}", err);
    for tip in err.debugging_tips() {
        eprintln!("  - {}", tip);
    }
}

Trait Implementations

impl Debug for Error

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

Formats the value using the given formatter.

impl Display for Error

Implementation of the Display trait for Error enum.

Provides human-readable error messages for each error variant.

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

Formats the value using the given formatter.

impl Error for Error

Implementation of the standard Error trait for rsactor Error enum.

This allows Error to be used with standard error handling mechanisms.

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.