Protocol errors

SDK · 12

The SDK is deliberately thin on bespoke exceptions. DendriteProtocolError (a ValueError subclass) is raised for protocol misuse - e.g. when you emit() a Signal whose type isn’t in SYNAPSE_TYPES. The Engram surface adds EngramError and its subclasses, and Pathways raise PathwayClosedError when closed early. Everything else surfaces as a standard library or dependency exception.

errors.py

# Protocol misuse:
class DendriteProtocolError(ValueError): ...   # illegal emit() / await_decision type
CortexProtocolError = DendriteProtocolError   # back-compat alias

# Engram errors (see the Engram reference):
#   EngramError, EngramTimeout, EngramCancelled, EngramNotBound, EngramOverloaded

# Pathway:
#   PathwayClosedError  -  Pathway closed before a matching Signal arrived

# Everything else surfaces as a stdlib / dependency exception:
#   ValueError        -  bad envelope id prefix, unknown synapse URL scheme
#   TypeError         -  Dendrite built without a synapse
#   pydantic.ValidationError  -  malformed Signal fields
#   transport errors  -  raised straight from nats-py / aiokafka / asyncpg

# Usage
try:
    await dendrite.emit(some_agent_output_signal)
except DendriteProtocolError as e:
    log.error("Dendrite may only emit synapse-side types: %s", e)

Exception	Raised when
`DendriteProtocolError`	`dendrite.emit()` is called with a Signal type not in `SYNAPSE_TYPES` (e.g. a worker trying to emit a TASK).
`ValueError`	Bad envelope id prefix (not `evt_` / `trc_`), or unknown Synapse URL scheme.
`TypeError`	Dendrite constructed without a `synapse=` argument.
`pydantic.ValidationError`	Malformed Signal fields on decode (wire format does not match the envelope schema).
Transport exception	Raised directly from `nats-py`, `aiokafka`, or `asyncpg` - not wrapped.

Have a feature in mind?

The protocol, SDKs, and CLI are still pre-1.0. If something here is missing, ambiguous, or wrong - open an issue and propose a change. Every breaking change is debated in DECISIONS.md first.

Run the quickstart →Re-read the envelope spec