Error Taxonomy¶

Complete catalog of all exceptions raised by the cosalette framework. Errors are grouped by when they occur: during registration (app setup), at runtime (after bootstrap), or through the error publishing pipeline.

Registration-Time Errors¶

These exceptions are raised before the app starts running — during device registration, decorator application, or App() construction. They indicate a programming mistake in your setup code.

TypeError¶

Registration TypeError exceptions mean the framework received a value of the wrong type, or a callback/handler violates a structural requirement.

Decorator Parentheses¶

Raised when @app.device or @app.command is used without parentheses.

Cause: Python calls the decorator with the function as the first argument when parentheses are missing, which is never the intended use.

Async init Callback¶

Raised when the init= parameter of @app.device() receives an async function or a callable with an async __call__.

Cause: The init= callback runs during synchronous bootstrap. Async functions cannot be awaited in that phase.

init Result Shadows Injectable¶

Raised when the init= callback returns a type that the framework already provides via dependency injection (e.g. AppContext, MqttPort).

Bool Parameters (Type Guard)¶

Because bool is a subclass of int (and float), numeric constructor parameters explicitly reject booleans to catch accidental True/False arguments.

Cause: isinstance(True, int) is True in Python, so without an explicit guard, Pt1Filter(tau=True) would silently pass as tau=1.

Non-Int window¶

Raised when MedianFilter(window=...) receives a value that is not an int (and not a bool).

Handler Annotation Errors¶

Raised when a device or command handler has parameters that the injection system cannot resolve.

Cause: The injection system resolves handler parameters by their type annotations. Every parameter must have a concrete type annotation — no *args, **kwargs, positional-only, or non-type annotations.

The unresolvable annotation variant means the annotation could not be evaluated at all — under from __future__ import annotations the annotation is a string that is resolved at registration time. The underlying exception is included in the message and chained as __cause__, so NameError: name 'Foo' is not defined really does mean a missing import. Errors raised by the DI markers themselves (see below) are reported verbatim instead.

Invalid Depends() Dependency¶

Raised by Depends() when the dependency callable cannot be supported. Under from __future__ import annotations the marker is constructed when the handler's annotations are resolved (registration time), not at def time.

Cause: Dependencies are resolved synchronously while building handler kwargs, so nothing can await them. All three async forms are rejected: an async def function, an async generator function, and a callable object whose __call__ is either of those. Dependency injection plans are cached by dependency identity, so the callable must also be hashable.

Adapter __aenter__ Not Callable¶

Raised when an adapter has an __aenter__ attribute that is not callable.

Unresolved Interval¶

Raised when a telemetry device's interval is still a callable at runtime, meaning resolve_intervals() was never called during bootstrap.

Cause: This is an internal consistency error — the framework should resolve deferred intervals during bootstrap. If you see this, it may indicate a framework bug or manual misuse of internal APIs.

ValueError¶

Registration ValueError exceptions indicate a value that is the right type but violates a constraint (negative interval, duplicate name, etc.).

Negative or Zero Intervals¶

Raised when a time interval is not positive.

Duplicate Registration¶

Raised when registering a device name or handler that already exists.

Cause: Each device name must be unique within an app (see ADR-019 for scoped name uniqueness). The root device (unnamed) is limited to one.

Duplicate Adapter¶

Raised when registering a second adapter for the same port type.

Invalid Adapter Tuple¶

Raised when the adapters= dict value is a tuple that is not a 2-tuple.

Empty Group Name¶

Raised when a coalescing group name is an empty string.

Persist Without Store¶

Raised when a persist= policy (e.g. SaveOnPublish()) is registered on @app.telemetry and the app has explicitly opted out of persistence with store=None.

Filter and Strategy Parameters¶

Numeric parameters on filters and strategies must be within valid ranges.

Strategy Mutual Exclusion¶

Every() requires exactly one of seconds or n, not both and not neither.

Composite Policy Children¶

AnySavePolicy and AllSavePolicy require at least one child policy.

Composite Strategy Children¶

AnyStrategy and AllStrategy require at least one child strategy.

Import Path Format¶

Raised when an import path string does not follow the module.path:attr_name convention.

Runtime Errors¶

These exceptions are raised after the app has started — during bootstrap completion, MQTT operations, or store access.

TypeError¶

Runtime TypeError exceptions come from dependency resolution, which happens per dispatch so that adapters can be registered in any order.

Unresolved Provider¶

Raised when a handler parameter's type has no matching provider.

Cause: The type is neither a framework-provided injectable (DeviceContext, Settings, logging.Logger, ClockPort, …) nor a registered adapter port. Resolution is deliberately deferred to dispatch time, so a missing app.adapter() call surfaces here rather than at registration.

Awaitable Dependency Result¶

Raised when a synchronous Depends() callable returns a coroutine (or any other awaitable) — the case Depends() cannot detect statically.

Cause: Depends(lambda: async_fn()) passes every registration-time check because the lambda itself is synchronous. Injecting its result would hand the handler an un-awaited coroutine.

Circular Dependency¶

Raised when a Depends() callable depends on itself, directly or transitively.

Cause: Dependencies are resolved recursively; a cycle would otherwise exhaust the stack with a bare RecursionError.

Topic Marker Outside Request Context¶

Raised when a parameter annotated with Annotated[str, Topic()] is dispatched in a context that carries no MQTT topic — for example, a scheduled telemetry cycle (not triggered by an incoming message).

Cause: Topic() extracts the topic from the current MQTT message. Telemetry and periodic handlers run on a schedule and have no inbound message, so the topic is None at dispatch time.

Message Type Outside Request Context¶

Raised when a parameter is annotated with the Message type and the handler runs in a non-command context (no inbound MQTT topic or payload).

Cause: Message bundles the raw MQTT topic and payload into a single object. Outside a command handler, neither is available.

RuntimeError¶

Settings Unavailable¶

Raised when the settings model cannot be instantiated, typically because required environment variables are missing.

MQTT Not Connected¶

Raised when attempting to publish or subscribe but the MQTT client is not connected.

Cause: Publishing was attempted before the MQTT client connected, or after it disconnected. The framework manages connection lifecycle automatically — this typically indicates use of the MqttClient outside the normal lifecycle.

aiomqtt Not Installed¶

Raised when MqttClient is instantiated but the aiomqtt package is not available.

Store Not Loaded¶

Raised when accessing DeviceStore data before load() has been called.

Cause: The framework calls load() during bootstrap. This error indicates manual use of DeviceStore outside the normal lifecycle, or a framework bug.

Store Not Set¶

Raised internally when create_device_store() is called but no store backend was configured.

LookupError¶

Adapter Not Found¶

Raised when requesting an adapter for a port type that was never registered.

CLI Errors¶

These exceptions are raised by the CLI layer (Typer) when the user provides invalid command-line arguments.

typer.BadParameter¶

SystemExit¶

The CLI exits with code 1 (EXIT_CONFIG_ERROR) when the configuration model raises a validation error (e.g. from pydantic).

Error Publishing Pipeline¶

The framework includes a built-in error publishing system for reporting runtime errors via MQTT. This section summarizes the pipeline — for full details, see Error Handling (concept) and Payload Schemas.

Pipeline Flow¶

Exception raised in device function
    ↓
build_error_payload(error, error_type_map=..., device=...)
    ↓
ErrorPayload(error_type, message, device, timestamp, details)
    ↓
ErrorPublisher.publish()
    ↓
MQTT: {prefix}/error              (global, always)
MQTT: {prefix}/{device}/error     (per-device, when device known)

error_type_map Pattern¶

The error_type_map is a dict[type[Exception], str] that maps exact exception classes (no subclass matching) to machine-readable error_type strings. Unmapped exceptions produce "error" as the type.

error_type_map: dict[type[Exception], str] = {
    InvalidCommandError: "invalid_command",
    TimeoutError: "timeout",
    ConnectionError: "connection_lost",
}

disclose_messages_for Pattern¶

disclose_messages_for (frozenset[type[Exception]] | None = None) decouples message disclosure from error_type_map's labeling (F-DP1, ADR-061). It is accepted by App, ErrorPublisher, build_error_payload(), AppHarness.create(), and create_services().

verbose=True (MqttSettings.error_publish_verbose) still overrides both and discloses every message unconditionally.

app = cosalette.App(
    name="caldates2mqtt",
    error_type_map={CalDavConnectionError: "caldav_connection_error"},
    disclose_messages_for=frozenset(),  # label it, but keep the message redacted
)

Publication Behaviour¶

Topic Layout¶

Root devices (unnamed) only publish to the global topic to avoid duplicating the same error on both topics.

See Also¶

• Error Handling (concept) — design principles and rationale
• Payload Schemas — JSON schema for ErrorPayload
• Handling Errors (guide) — fix examples for each error class, and how to use build_error_payload() with custom exceptions
• ADR-011 — architecture decision record
• ADR-061 — decoupled disclose_messages_for message-disclosure policy