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#

The shard-mapper scaling error. The EventBus scaling methods are manual_scale_up(count: u16) / manual_scale_down(count: u16), and both return AdapterError; ScalingError is the mapper-level type underneath.

ConfigError#

Returned from EventBusConfigBuilder::build().

One variant — match it, read the string to see which knob.

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)#

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

There is no NoServer / NoMatchingServer / Panic variant — a handler that panics or returns a typed application error surfaces as ServerError { status, message, headers }, carrying the wire-stable status codes NRPC_TYPED_BAD_REQUEST / NRPC_TYPED_HANDLER_ERROR (part of the cross-language fixture). The binding-native typed wrappers (TS / Python / Go) re-raise these as idiomatic exceptions.

Per-peer stream errors (StreamError)#

Returned from the per-peer stream API on MeshNode.

WindowFull and stream reset live below this surface — the tx-credit admittance value and the SUBPROTOCOL_STREAM_RESET wire message, respectively — they are not StreamError variants.

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.