Skip to content

xtr_messenger.exception

Every error this library raises.

All of them derive from :class:MessageBusError, so one except catches anything the bus can go wrong with, and a narrower one handles a single cause. Each carries the data a caller needs as typed attributes rather than forcing a message to be parsed.

DelayedMessageHandlingError

DelayedMessageHandlingError(envelope: Envelope, failures: Sequence[tuple[Envelope, Exception]])

Bases: MessageBusError

One or more messages held back with a DispatchAfterCurrentBusStamp failed.

The message being handled succeeded — what it did stands — and then the messages its handling held back were dispatched, each in turn, every one tried even when an earlier one failed. The first failure is the cause.

Attributes:

  • envelope (Envelope) –

    The message whose handling held them back, as its handling left it.

  • failures (tuple[tuple[Envelope, Exception], ...]) –

    Each held-back message that failed, with what its dispatch raised, in the order dispatched.

  • errors (tuple[Exception, ...]) –

    What each failed dispatch raised, in the same order.

Record the message that succeeded and each held-back message that then failed.

HandlerSignatureError

HandlerSignatureError(handler_name: str, parameters: tuple[str, ...])

Bases: MessageBusError

A handler's parameters are not a shape the bus can call.

Record the handler and the parameters it declared.

HandlersFailedError

HandlersFailedError(envelope: Envelope, errors: Mapping[str, Exception])

Bases: MessageBusError

One or more handlers of a message raised, after every handler had its turn.

One failing handler does not keep the others from running: each is independent, and an unrelated one — an audit trail, a metric — must not go quiet because another broke. What every handler that failed raised is kept, by handler name, and the first of them is the cause.

Attributes:

  • envelope (Envelope) –

    The message as handling left it, with a :class:~xtr_messenger.stamp.HandledStamp for every handler that succeeded.

  • errors (Mapping[str, Exception]) –

    What each failed handler raised, by handler name, in the order the handlers ran; a name another failed handler already took is told apart as name#2, name#3….

Record the envelope handling left and what each failed handler raised.

IncompatibleReceiversError

IncompatibleReceiversError(brokered: tuple[str, ...], registered: tuple[str, ...])

Bases: MessageBusError

A transport that brings its own worker was asked to share it with receivers.

A broker that runs its own consume loop — taskiq does — cannot also drive a receiver registered with the application, and the library's own loop cannot drive the broker. Run them as separate workers.

Record the transports with their own worker, and the receivers asked alongside.

InvalidDsnError

InvalidDsnError(dsn: str, reason: str | None = None)

Bases: MessageBusError

A DSN that cannot be read into a transport selection.

The message shows the DSN redacted, never as written — an invalid DSN is exactly the kind whose credentials end up somewhere unexpected.

Record the DSN that could not be read, and why.

Without reason, the DSN is missing the scheme that selects its transport — the commonest way one goes wrong.

InvalidMiddlewareArgumentsError

InvalidMiddlewareArgumentsError(name: str, reason: str)

Bases: MessageBusError

The configuration gives middleware arguments it does not take.

A configuration entry {name: {argument: value}} naming an argument the middleware's builder does not take, or written in another shape, is refused. With a container, an argument naming no constructor parameter fails the build like any definition argument.

Attributes:

  • name (str) –

    The middleware the arguments were for.

  • reason (str) –

    What is wrong with them.

Record which middleware was misconfigured, and how.

InvalidTransportOptionError

InvalidTransportOptionError(option: str, value: str, expected: str)

Bases: MessageBusError

A transport setting holds a value its adapter cannot use.

The setting may have come from the DSN's query string or from options — both reach an adapter the same way, so neither is named.

Record the setting, the value it held, and what it should hold.

MessageBusError

Bases: Exception

Base class for every error raised by this library.

Catch this to handle anything the bus can go wrong with; catch a subclass to handle one cause. Every subclass carries the data a caller needs as typed attributes and composes its own message from them.

MessageDecodingFailedError

MessageDecodingFailedError(reason: str, message_name: str | None = None)

Bases: MessageBusError

An encoded envelope could not be turned back into a typed message.

Deliberately loud: a silently mis-decoded payload reaches the handler as the wrong shape and fails far from its cause.

Record why decoding failed, and for which message when known.

MessageEncodingFailedError

MessageEncodingFailedError(reason: str, message_name: str)

Bases: MessageBusError

A message could not be turned into something a transport can carry.

Raised on the producer's side, before anything is sent — a message or a stamp holding a value the serializer cannot write, or would not read back exactly.

Record why encoding failed, and for which message.

MissingSerializerError

MissingSerializerError(scheme: str, reason: str)

Bases: MessageBusError

A transport has to write its messages, and was given nothing to write them with.

Raised where the transport is built, never when the application boots: a process speaking only sync:// has no messages to write and needs no serializer, so its absence only matters once a transport would use it.

Record which scheme needed the serializer, and where to give it one.

MixedDsnError

MixedDsnError(dsns: tuple[str, ...])

Bases: MessageBusError

A worker was asked to serve transports that live on different brokers.

Record the conflicting DSNs, redacted — an attribute leaks as easily as a message.

NoFailureTransportError

NoFailureTransportError(known: tuple[str, ...])

Bases: MessageBusError

No failure transport was named, and the configuration has no default one.

Record the failure transports there are to choose from.

NoHandlerForMessageError

NoHandlerForMessageError(message_type: type, handled_types: tuple[str, ...])

Bases: MessageBusError

No handler is registered for a message that reached handling.

In a worker this almost always means the module declaring the handler was never imported, so the registration decorator never ran. Failing is the safe reading: the alternative is acknowledging the message and losing it silently.

Record the unhandled type alongside the types that do have handlers.

NoSenderForMessageError

NoSenderForMessageError(message_type: type, routed_types: tuple[str, ...])

Bases: MessageBusError

No transport is routed for a dispatched message type.

Raised before any transport is touched, so nothing was enqueued when it surfaces.

Record the unrouted type alongside the types that are routed.

NotConsumableError

NotConsumableError(names: tuple[str, ...], scheme: str)

Bases: MessageBusError

A transport sends but cannot be consumed, and brings no worker either.

Reaching this means an adapter implements only the sending half and does not implement :class:~xtr_messenger.worker_providing_interface.WorkerProvidingInterface, so there is nothing to run and no way to build it.

Record which transports were asked for, and their scheme.

UnknownMessageNameError

UnknownMessageNameError(name: str)

Bases: MessageBusError

A wire message name could not be resolved back to a Python type.

Record the unresolvable name.

UnknownMiddlewareError

UnknownMiddlewareError(name: str, known: tuple[str, ...])

Bases: MessageBusError

The configuration names middleware this process has nothing registered for.

Record what was named, and what a name may actually be.

UnknownTransportError

UnknownTransportError(names: tuple[str, ...], known: tuple[str, ...])

Bases: MessageBusError

A route or a worker names a transport the configuration does not define.

Record what was asked for, and what is actually configured.

UnknownTransportOptionError

UnknownTransportOptionError(scheme: str, unknown: tuple[str, ...], known: tuple[str, ...])

Bases: MessageBusError

A transport DSN carries an option its adapter does not recognise.

Raised rather than ignored because an unrecognised option is always a mistake in configuration someone wrote by hand — a typo, or a setting meant for a different scheme. Dropping it silently leaves the transport running on defaults that nobody chose, which is the failure this exists to prevent.

Record the scheme, what it did not recognise, and what it accepts.

UnsupportedDsnError

UnsupportedDsnError(transport_name: str, dsn: str)

Bases: MessageBusError

No factory recognised a transport's DSN.

Record which transport could not be built, and from what.

UnsupportedStampError

UnsupportedStampError(stamp_name: str, transport: str)

Bases: MessageBusError

A transport was handed a stamp it cannot act on.

A stamp a transport ignores is a silent failure: the caller asked for behaviour — a delay, say — and the message went out immediately with no sign the request was dropped. Raising names the stamp and the transport so the mismatch surfaces where it is made, not as a message that never behaved as asked.

Record which stamp could not be honoured, and by which transport.

UnsupportedTransportOperationError

UnsupportedTransportOperationError(transport: str, operation: str)

Bases: MessageBusError

A transport cannot list, count, find or receive, and was asked to.

What a transport can do beyond sending is what it implements: listing and finding messages is :class:~xtr_messenger.transport.receiver.ListableReceiverInterface, receiving is :class:~xtr_messenger.transport.receiver.ReceiverInterface.

Record the transport and what it was asked to do — "list messages", say.