Enum OutboxError 

#[non_exhaustive]
pub enum OutboxError {
    Serialization(Error),
    Database(Box<dyn Error + Send + Sync>),
    MissingHandler {
        event_type: String,
    },
    MaxRetries {
        event_id: Uuid,
        attempts: u32,
    },
    TypeMismatch {
        expected: &'static str,
        actual: String,
    },
    PoolTimeout,
    DispatchTimeout {
        event_id: Uuid,
        event_type: String,
        timeout: Duration,
    },
    Internal(String),
}

Errors raised by the outbox primitives, publishers and workers.

Marked #[non_exhaustive] so new variants can be added without a breaking change.

Variants (Non-exhaustive)

Non-exhaustive enums could have additional variants added in future. Therefore, when matching against variants of non-exhaustive enums, an extra wildcard arm must be added to account for any future variants.

Serialization(Error)

The event payload could not be serialized or deserialized as JSON.

Database(Box<dyn Error + Send + Sync>)

The backend reported a database-level failure.

The original error is preserved as a boxed source so callers can downcast if they need typed access to the underlying driver error.

MissingHandler

The worker polled an envelope whose event_type has no registered handler.

Fields

event_type: String

The unrouted event type read from the envelope.

MaxRetries

Reserved for future use. Not constructed by the current outbox worker implementation.

The worker today leaves exhausted events in the table (where they are excluded from future polls by the attempts < max_attempts predicate) or moves them to the dead-letter table when one is configured. This variant is kept in the enum so a future release can expose exhaustion as a typed error without a breaking change. Do not match on it expecting to observe it in normal operation.

Fields

event_id: Uuid

Identifier of the event that exhausted its retry budget.

attempts: u32

Number of attempts already consumed.

TypeMismatch

An envelope was decoded into the wrong event type.

Returned when a caller invokes crate::OutboxEnvelope::decode with a type whose crate::Event::EVENT_TYPE does not match the envelope’s event_type field. Typically the sign of a router or registry misconfiguration on the caller side.

Fields

expected: &'static str

Event type requested by the caller (E::EVENT_TYPE).

actual: String

Event type actually stored in the envelope.

PoolTimeout

The connection pool did not yield a connection within the configured timeout.

This is a transient condition: the pool is under pressure but the database itself may be healthy. The outbox worker retries automatically after OutboxWorkerConfig::poll_interval. Application code that observes this variant can implement back-pressure or circuit-breaking.

To prevent indefinite blocking, configure an acquire timeout on the pool (e.g. sqlx::pool::PoolOptions::acquire_timeout).

DispatchTimeout

The handler did not complete within OutboxWorkerConfig::dispatch_timeout.

The worker enforces dispatch_timeout as a hard deadline around each handler invocation. When it elapses the dispatch is treated as a failed attempt (recorded via crate::OutboxStore::mark_failed and retried or dead-lettered like any other error) and the handler’s cancellation token is signalled so cooperative handlers can unwind.

Fields

event_id: Uuid

Identifier of the event whose handler timed out.

event_type: String

The unrouted event type read from the envelope.

timeout: Duration

The configured dispatch timeout that elapsed.

Internal(String)

An invariant of the outbox machinery was violated.

Signals a bug in the framework itself, not a recoverable error. Report occurrences upstream.

Trait Implementations

impl Debug for OutboxError

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

Formats the value using the given formatter.

impl Display for OutboxError

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

Formats the value using the given formatter.

impl Error for OutboxError

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 OutboxError

fn from(source: Error) -> Self

Converts to this type from the input type.