Error Codes#

This page enumerates every error type the core crate surfaces. Errors are organized by the operation they come from — ingestion, consumption, and adapter — and each variant includes the conditions under which it fires and the right response from a caller.

The crate uses thiserror throughout, so every variant has a Display impl and (where it wraps another error) a working source() chain. Pattern match on the variant when you need to make a decision; format the Display when you need to log.

IngestionError#

Returned from EventBus::ingest() and EventBus::ingest_raw().

Unrouted is distinct from Backpressure so callers can apply the right remediation. Backpressure says "the destination is full"; unrouted says "there's no destination right now." Pre-fix versions of the bus collapsed these into one variant, and callers applied back-off-and-retry to unrouted errors that wouldn't be fixed by waiting — they needed to retry until the topology settled, which is a different shape of retry.

ConsumerError#

Returned from EventBus::poll().

A ConsumerError::Adapter wraps an AdapterError, so the full classification surface is available through the wrapped error. Use From<AdapterError> to convert, or pattern match on the wrapper.

AdapterError#

Returned from adapter operations (Adapter::on_batch, Adapter::poll_shard, Adapter::flush, Adapter::shutdown). Also wrapped in ConsumerError.

Classification methods#

impl AdapterError {
    pub fn is_retryable(&self) -> bool;
    pub fn is_fatal(&self) -> bool;
    pub fn is_shutdown(&self) -> bool;
}

The bus's dispatch loop reads these to decide what to do with a failed batch:

• Retryable. The batch is requeued with an exponential backoff up to a bounded number of attempts.
• Fatal. The batch is dropped, the bus's stats record the drop, and the error is logged at error level.
• Shutdown. The batch is dropped and ingestion is halted; the bus's shutdown is presumed to be in flight.
• Connection (default). Conservatively non-retryable. The bus skips the retry loop and drops the batch immediately. This avoids burning the retry budget on a backend that's gone for good.

The default decision for Connection errors is conservative on purpose. If you know your backend's connection errors are transient and you want them retried, return AdapterError::Transient(...) from your adapter instead.

Subsystem-specific errors#

Beyond the core trio, individual subsystems define their own error types. The ones most likely to surface in application code:

ScalingError#

Returned from EventBus::add_shards() and EventBus::remove_shards().

ConfigError#

Returned from EventBusConfigBuilder::build().

Adapter-specific errors#

Each shipped adapter has its own error type with backend-specific variants. The most useful ones from each:

• NetAdapter — NetAdapterError::SessionFailed, NetAdapterError::RoutingFailed, NetAdapterError::AuthRejected.
• RedisAdapter — wraps redis::RedisError with classification ("retryable" for read timeouts and replica failovers, "fatal" for auth failures).
• JetStreamAdapter — wraps async-nats::Error with similar classification.

These are surfaced through AdapterError::Connection, AdapterError::Transient, or AdapterError::Fatal as appropriate, so callers don't need to know the specific backend to apply the right policy. Match on the AdapterError variant, not on the inner error, unless you have a backend-specific reason.

TokenError#

Returned from the channel-auth token issuance and verification paths in net::adapter::net::identity.

The TTL ceiling is a hard cap on the auth surface — issuing a token past one year is rejected on the fallible path and clamped on the SDK's infallible path. Long-lived grants need periodic re-issue, which re-checks the issuer's signing key and current policy.

TagMatcherError#

Returned from capability-tag matchers when the requested matcher can't be compiled or evaluated.

The regex Cargo feature is off by default — regex matching adds about 1.1 MiB to binding artifacts, and most callers don't need it. Builds that do can opt in. Pre-v0.24 the regex-less fallback silently returned empty matches, which made misconfigured queries look indistinguishable from "no entries match"; v0.24 replaced that with the structured error above.

nRPC errors (RpcError, RpcAppError)#

Returned from call_typed, call_streaming_typed, call_client_stream_typed, call_duplex_typed, and the underlying MeshRpc surface.

The codec error sub-classification is used by every binding's typed wrapper to surface the failure as a binding-native error type (TS / Python / Go all have idiomatic equivalents). The RpcAppError shape is wire-stable across languages — codes like NRPC_TYPED_BAD_REQUEST and NRPC_TYPED_HANDLER_ERROR are part of the cross-language fixture.

Reliable-stream errors (StreamError)#

Returned from the reliable-stream API on MeshNode.

A note on credentials in URLs#

Adapter constructors and Debug impls scrub user:password@ from connection URLs before logging or rendering. A misconfigured operator who put a password directly in the URL won't leak it into log sinks — the redactor identifies the rightmost @ in the authority component and replaces the userinfo with [REDACTED].

This is per-adapter behavior, not part of the error API itself, but it shows up in Debug output of every adapter config and is worth knowing about when reading logs.