2.4 Error Handling

Error Handling

Unified backend failures live in BackendError. Structured ZeroMQ transport failures use ZmqMessageError (feature zmq) and map into BackendError on the hybrid adapter. Tip for this page: 08d2f28 / #55.

BackendError

Variant	Meaning
InitializationError(String)	Setup / model load / connect failures
ProcessingError(String)	Failures during process_batch
ModelError(String)	Save/load / filesystem I/O
CommunicationError(String)	Transport, framing, structural decode, closed sockets, second held sibling
InvalidInput(String)	Caller/payload validation (incl. hybrid envelope payload Validate failures)
Protocol(ProtocolError)	Wire-valid IpcMessage that is the wrong variant for this call (new in #55)

Display strings (for example Initialization failed: …, Invalid input: …) come from thiserror 2.x derives since 5e4562b (LIM-1451, was 1.0). Display text, Error::source (None for the string variants; Protocol is transparent, so its Display equals the inner ProtocolError and its source is None), and variant matches are unchanged, and unit tests in src/error.rs now pin them.

Exhaustive matches on BackendError need a Protocol arm. Wire version stays 1. The REST mapper still treats Protocol as a backend failure (HTTP 502); the router does not expose hybrid-flow sockets (CHANGELOG Unreleased).

ProtocolError

Variant	Meaning
UnexpectedVariant { found, expected }	Decoded/validated message was not the variant this receive method accepts; frame already consumed

ZmqMessageError (feature zmq)

Matchable outcomes from ZmqMessagePublisher / ZmqMessageSubscriber: InvalidConfig, Setup, Validation, Encode, FrameTooLarge, Envelope, UnexpectedFraming(FramingFault), WouldBlock, HighWaterMark, Closed, Transport. See 3.4.

Propagation

flowchart TD
  Rust["RustBackend"] --> BE["BackendError"]
  ZmqRO["ZmqIpcBackend"] --> BE
  Hybrid["ZmqHybridFlowBackend"] --> ZME["ZmqMessageError"]
  ZME -->|"map_transport_error"| BE
  Hybrid -->|"wrong variant"| Proto["BackendError::Protocol"]
  Hybrid -->|"Validate fail"| Inv["BackendError::InvalidInput"]
  BE --> Caller["IpcBackend / HybridFlowBackend caller"]

Loading

Hybrid receive cheat sheet

Outcome	Result
Nothing queued	Ok(None)
Expected variant	Ok(Some(...))
Sibling held / second sibling / framing / closed	CommunicationError (or mapped from ZmqMessageError)
Unrelated variant	Protocol(UnexpectedVariant)
Payload fails Validate	InvalidInput

Sources: src/error.rs, src/zmq_message/hybrid.rs, src/trait_def.rs