Enum LaserError 

#[non_exhaustive]
pub enum LaserError {
    PublishFailed(Box<PublishFailure>),
    Handler(String),
    HandlerConfig(String),
    Rejected(String),
    Timeout(&'static str),
    AmbiguousMutation(String),
    NoRespondTopic,
    StateStore(String),
    Config(&'static str),
    NoStream,
    Query(QueryError),
    Kv(KvError),
    Fork(ForkError),
    Session(SessionError),
    Graph(GraphError),
    Authz(AuthzError),
    Filter(FilterError),
    FilterFault {
        partition_id: u32,
        offset: u64,
        reason: FaultReason,
    },
    FilterOversizedRecord {
        partition_id: u32,
        offset: u64,
    },
    ConsumerGroupSetup {
        group_id: u32,
        name: String,
        identity: FilterGroupIdentity,
        source: Box<LaserError>,
    },
    Checkpoint(Box<CheckpointError>),
    Codec(String),
    Invalid(String),
    Protocol(String),
    Command(CommandError),
    Unsupported {
        surface: &'static str,
        feature: Option<&'static str>,
        message: String,
    },
    Integrity {
        reference: String,
    },
    Signature(String),
    PolicyBlocked(String),
    StepUpRequired {
        scope: String,
    },
    PolicyDeferred(String),
    NoCapableAgent {
        skill: String,
    },
    NoInbox {
        agent: String,
    },
    PresenceConflict {
        advertised: String,
        requested: String,
    },
    RoutePrincipalMismatch {
        agent: String,
        expected: u32,
        actual: Option<u32>,
    },
    FenceViolation {
        stale: u64,
        current: u64,
    },
    BudgetExceeded {
        ceiling: u64,
        spent: u64,
    },
    Cancelled {
        run: String,
    },
    Quarantined {
        agent: String,
    },
    Iggy(IggyError),
    Id(IdError),
    Provenance(ProvenanceError),
}

The one error type every fallible SDK call returns.

LaserData-Cloud-served surfaces fail with their typed wire error nested intact (Query, Kv, Fork), so callers can match on the structured cause (QueryError::TooLarge { cap, .. }, KvError::InvalidKey, …) instead of parsing strings. Client-side failures keep their own variants: Codec (encode/decode), Invalid (validation), Protocol (unexpected reply shape). The classifier methods (is_retryable, is_unsupported, is_not_found) answer the common questions without matching variants.

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.

PublishFailed(Box<PublishFailure>)

A fluent or direct publish that gave up. Carries the cause, the target, the ranges that committed, and the records left unconfirmed.

Handler(String)

A transient handler-side failure a handler may return to request a retry (the reliable consumer retries it under the RetryPolicy). Deterministic wiring, startup, and configuration failures use HandlerConfig instead, which never retries.

HandlerConfig(String)

A deterministic handler wiring, startup, or configuration failure: a task that stopped before becoming ready, a join failure, an invalid inbox topic or task id, a missing correlation or agent id. Retrying cannot change the outcome, so it is never retryable (the reliable consumer dead-letters it at once rather than burning the retry budget).

Rejected(String)

Timeout(&'static str)

AmbiguousMutation(String)

A managed mutation’s outcome is unknown: the attempt timed out or the transport failed after dispatch, so the server may or may not have applied it. This is deliberately not generically retryable. The caller must inspect is_ambiguous_mutation and follow the operation-specific recovery contract.

NoRespondTopic

StateStore(String)

Config(&'static str)

NoStream

Query(QueryError)

LaserData Cloud answered a query/browse/control op with a typed failure.

Kv(KvError)

LaserData Cloud answered a key-value op with a typed failure.

Fork(ForkError)

LaserData Cloud answered a fork op with a typed failure.

Session(SessionError)

LaserData Cloud answered a session read with a typed failure.

Graph(GraphError)

LaserData Cloud answered a graph op with a typed failure.

Authz(AuthzError)

The streaming server answered an authorization op with a typed failure.

Filter(FilterError)

The streaming server or the filter catalog answered a consumer-filter operation with a typed failure.

FilterFault

A filtered read stopped in front of a record the filter could not evaluate under the stop fault policy. The record and everything after it stay unacknowledged.

Fields

partition_id: u32

offset: u64

reason: FaultReason

FilterOversizedRecord

A matching record alone exceeds the filtered reply cap, so no page can carry it. The record and everything after it stay unacknowledged.

Fields

partition_id: u32

offset: u64

ConsumerGroupSetup

The consumer group was created, or already existed, but its filter could not be configured. The group stays as it is, unbound unless it ran a policy before, and no reader joined it. source is the typed catalog refusal or transport failure.

Fields

group_id: u32

name: String

identity: FilterGroupIdentity

source: Box<LaserError>

Checkpoint(Box<CheckpointError>)

Iggy answered a destination or checkpoint operation with a typed failure.

Codec(String)

A client-side encode or decode failed (payload codec, wire envelope, reply bytes). Deterministic for a given input, so never retryable.

Invalid(String)

Client-side validation rejected the input before any round-trip (size caps, reserved keys, malformed identifiers).

Protocol(String)

The reply decoded but carried an outcome the request cannot accept (e.g. a scan outcome for a get). Indicates server/client skew.

Command(CommandError)

A managed endpoint returned its original result code and message.

Unsupported

The connected infrastructure does not provide the requested feature (Apache Iggy without LaserData Cloud, or a deployment whose backend does not advertise the sub-capability). Permanent by definition: gate the code path on Laser::capabilities instead of retrying. surface names the accessor the call came through and feature the sub-capability when one exists, so a log line says what was refused without parsing prose. Build with unsupported / unsupported_feature.

Fields

surface: &'static str

The surface the refused call came through ("query", "kv", …).

feature: Option<&'static str>

The sub-capability within the surface, when one exists ("cas_fenced", "keyword", "watch", …).

message: String

What was asked and why it was refused.

Integrity

A claim-checked body failed its digest check: the blob store returned bytes whose SHA-256 does not match the BodyRef capsule’s. Never surfaced with the fetched bytes attached, so an integrity failure can never be mistaken for the body.

Fields

reference: String

The capsule reference whose bytes failed verification.

Signature(String)

An envelope signature was absent where required, enrolled to no known key, or failed verification. The authorship and authorization gate, never retryable.

PolicyBlocked(String)

The enrolled ActionGovernor rejected the action before the effect ran. Never retryable: the policy, not the transport, said no.

StepUpRequired

The enrolled governor paused the action on a stronger approval. scope names the scope the approval must grant, so a handler can run an approval_gate and re-send. Never retryable as-is.

Fields

scope: String

PolicyDeferred(String)

The enrolled governor held the action for later execution. Retryable by definition: later is the point.

NoCapableAgent

Capability routing found no live agent advertising skill. The caller retries after the registry refreshes, or routes elsewhere.

Fields

skill: String

NoInbox

An advertised inbox route resolved a capable agent but the agent advertises no inbox topic in its live presence, so there is nowhere to address it. The caller waits for the agent to advertise, supplies an explicit InboxRoute::Fixed, or routes elsewhere. Never falls back to a shared topic name.

Fields

agent: String

PresenceConflict

One physical connection may advertise one logical agent. A second agent would overwrite connection metadata and steal the first agent’s route.

Fields

advertised: String

requested: String

RoutePrincipalMismatch

A route selected an agent claim whose live connection is not bound to the authenticated principal the caller required.

Fields

agent: String

expected: u32

actual: Option<u32>

FenceViolation

A fenced write lost the fence: the held token is below the live sequence, so a newer holder owns the task. Not alarming and never retryable by the loser, it is the at-most-one-effective-writer gate doing its job.

Fields

stale: u64

current: u64

BudgetExceeded

A spend ceiling was reached. Not retryable until the ceiling is raised.

Fields

ceiling: u64

spent: u64

Cancelled

A registered run’s recorded cancel intent was observed at a step boundary. The completed steps’ compensations have run. Not retryable on the same run.

Fields

run: String

Quarantined

The agent was quarantined and may not act. Not retryable.

Fields

agent: String

Iggy(IggyError)

Id(IdError)

Provenance(ProvenanceError)

Implementations

impl LaserError

pub fn publish_cause(&self) -> &Self

pub fn rejected(reason: impl Into<String>) -> Self

A handler returns this to reject a message permanently: the reliable consumer dead-letters it immediately instead of retrying.

pub fn unsupported(surface: &'static str, message: impl Into<String>) -> Self

An unsupported-surface refusal: the whole surface is absent on the connected deployment (e.g. any managed call against Apache Iggy).

pub fn unsupported_feature( surface: &'static str, feature: &'static str, message: impl Into<String>, ) -> Self

An unsupported-feature refusal: the surface is served but this sub-capability is not advertised (e.g. kv.cas_fenced, query.keyword).

pub fn is_retryable(&self) -> bool

Whether retrying the same call can succeed. Managed failures follow the canonical ResultCode classifier, while transport, handler, routing, timeout, and deferred-policy failures retain their local semantics.

pub fn is_unavailable(&self) -> bool

Whether the failure was transient: the store was momentarily out of reach, a connection was refused or dropped, or a concurrency conflict was aborted. The identical request may succeed on a later attempt, so this is the flag a retry loop keys on when it wants only the recoverable class rather than everything is_retryable admits.

pub fn is_not_leader(&self) -> bool

Whether the connected managed backend declined a conditional write because it does not own that operation’s mutation partition.

pub fn is_unsupported(&self) -> bool

Whether the failure means the connected infrastructure (or backend) does not provide the feature at all. Permanent: do not retry, gate the code path instead.

pub fn is_not_found(&self) -> bool

Whether the failure names a missing resource (index, fork). Distinct from a backend being down: the call worked, the thing is not there.

pub fn is_version_skew(&self) -> bool

Whether the failure is wire-version skew between this SDK and the connected LaserData Cloud (the envelope’s v was not accepted). Permanent for this client build: upgrade or downshift instead of retrying.

pub fn is_version_conflict(&self) -> bool

Whether a compare-and-swap lost its precondition (the key changed under it, or an expect_absent create lost a race). Not a failure to retry blindly: re-read the current value and version, recompute, and CAS again.

pub fn is_ambiguous_mutation(&self) -> bool

Whether a managed mutation may already have reached the server. A generic retry loop must stop: recovery depends on the operation. In particular, an ambiguous lease acquisition must wait through its requested TTL before a fresh acquisition, because an applied grant can otherwise conflict with itself and the reply carries no token to renew or release it.

pub fn is_stale(&self) -> bool

Whether a read-consistency barrier could not be met: a query projector or key-value fold has not yet applied the required source position. Retryable: the read model is catching up.

pub fn is_permission_denied(&self) -> bool

Whether the connected server refused the operation for missing permissions (the substrate’s RBAC: global permissions plus per-stream and per-topic grants). The principal exists and authenticated, the grant does not. The fix is an admin conversation, not a retry: ask for the stream or topic permission the failing verb needs (read, send, create), or point the client at a stream the principal can use.

pub fn is_stream_or_topic_not_found(&self) -> bool

Whether the target stream or topic does not exist FOR THIS PRINCIPAL. Under RBAC an existing stream the principal cannot see answers exactly like a missing one, so treat “not found” and “not permitted” as one user-facing question: does this principal have the stream, with the grant the verb needs? Especially relevant on deployments with server-managed dynamic streams, where the stream may simply not exist yet for this principal.

pub fn is_no_capable_agent(&self) -> bool

Whether capability routing found no live agent for the skill.

pub fn is_lease_lost(&self) -> bool

Whether a revocable lease was lost (expired, released, or re-acquired by another holder). For a fenced write, see is_fence_violation.

pub fn is_fence_violation(&self) -> bool

Whether a fenced write lost the fence (a stale holder stepped aside). Not alarming, never retryable by the loser.

pub fn is_budget_exceeded(&self) -> bool

Whether a spend ceiling was reached.

pub fn is_quarantined(&self) -> bool

Whether the agent is quarantined.

pub fn iggy_error_code(&self) -> Option<u32>

The Apache Iggy error code of the failure, when an Iggy error caused it. Reads through publish wrapping and a failed producer send, like the classifiers. Another SDK variant keeps its own classification.

pub fn filter_reason(&self) -> Option<FilterErrorReason>

The typed consumer-filter cause, when the failure is one.

pub fn code(&self) -> ResultCode

This failure’s place in the unified ResultCode space. A managed surface error projects onto its surface code, and a client-side failure maps to the closest code. Lets a caller branch on one dictionary instead of matching every variant, and mirrors the HTTP status the same error gets on the management surface.

Trait Implementations

impl Debug for LaserError

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

Formats the value using the given formatter.

impl Display for LaserError

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

Formats the value using the given formatter.

impl Error for LaserError

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<AuthzError> for LaserError

fn from(source: AuthzError) -> Self

Converts to this type from the input type.

impl From<CheckpointError> for LaserError

fn from(error: CheckpointError) -> Self

Converts to this type from the input type.

impl From<CommandError> for LaserError

fn from(error: CommandError) -> Self

Converts to this type from the input type.

impl From<DecodeError> for LaserError

fn from(error: DecodeError) -> Self

Converts to this type from the input type.

impl From<FilterError> for LaserError

fn from(source: FilterError) -> Self

Converts to this type from the input type.

impl From<ForkError> for LaserError

fn from(source: ForkError) -> Self

Converts to this type from the input type.

impl From<GraphError> for LaserError

fn from(source: GraphError) -> Self

Converts to this type from the input type.

impl From<IdError> for LaserError

fn from(source: IdError) -> Self

Converts to this type from the input type.

impl From<IggyError> for LaserError

fn from(source: IggyError) -> Self

Converts to this type from the input type.

impl From<IntentError> for LaserError

fn from(error: IntentError) -> Self

Converts to this type from the input type.

impl From<InvalidError> for LaserError

fn from(error: InvalidError) -> Self

Converts to this type from the input type.

impl From<KvError> for LaserError

fn from(source: KvError) -> Self

Converts to this type from the input type.

impl From<ProvenanceError> for LaserError

fn from(source: ProvenanceError) -> Self

Converts to this type from the input type.

impl From<QueryError> for LaserError

fn from(source: QueryError) -> Self

Converts to this type from the input type.

impl From<SessionError> for LaserError

fn from(source: SessionError) -> Self

Converts to this type from the input type.

impl From<TypedDecodeError> for LaserError

Folds into the codec family so records.next() composes with ? in a Result<_, LaserError> function, the position kept in the message.

fn from(error: TypedDecodeError) -> Self

Converts to this type from the input type.

impl From<ValidateError> for LaserError

fn from(error: ValidateError) -> Self

Converts to this type from the input type.