langchain-ai/deepagents · error · ValueError

Unknown external event kind: {self.kind!r}

Error message

Unknown external event kind: {self.kind!r}

What it means

`ExternalEvent.__post_init__` validates each event against a fixed set of recognized kinds before it enters the event bus. A kind outside `_VALID_KINDS` is rejected with this ValueError so malformed events never reach the Textual app's event loop where they would be silently unhandled.

Source

Thrown at libs/code/deepagents_code/event_bus.py:75

    """A transport-independent event delivered from outside the TUI."""

    kind: ExternalEventKind
    payload: str
    source: str
    bypass: BypassTier = BypassTier.QUEUED
    correlation_id: str | None = None

    def __post_init__(self) -> None:
        """Validate invariants for direct construction.

        Raises:
            ValueError: If `kind` is not a known kind, the payload is empty
                or whitespace-only, or the kind is `"signal"` but the payload
                is not a recognized signal name.
        """
        if self.kind not in _VALID_KINDS:
            msg = f"Unknown external event kind: {self.kind!r}"
            raise ValueError(msg)
        if not self.payload or not self.payload.strip():
            msg = "External event payload must be a non-empty string"
            raise ValueError(msg)
        if self.kind == "signal" and self.payload.strip().lower() not in _VALID_SIGNALS:
            msg = (
                f"Unknown external signal: {self.payload!r}; "
                f"expected one of {sorted(_VALID_SIGNALS)}"
            )
            raise ValueError(msg)


class EventSource(Protocol):
    """Source of external events for the Textual app.

    Implementations must be safe to `stop()` even when `start()` failed
    partway through; the app always invokes `stop()` from a `finally` block.
    """

View on GitHub (pinned to a1af029e6e)

Solutions

1. Use only kinds in `_VALID_KINDS` (see event_bus.py) for the exact allowed set.
2. Fix the kind spelling/casing on the producer side.
3. If a new kind is genuinely needed, add it to `_VALID_KINDS` plus handling logic — do not invent it at the call site.
4. Align producer and consumer to the same library version so kind vocabularies match.

Example fix

// before
ExternalEvent(kind="notification", payload="build done")
// after
ExternalEvent(kind="signal", payload="reload")

from deepagents_code.event_bus import ExternalEvent, _VALID_KINDS

def safe_event(kind: str, payload: str):
    if kind not in _VALID_KINDS:
        return None
    return ExternalEvent(kind=kind, payload=payload)

def is_valid_kind(kind: str) -> bool:
    return kind in _VALID_KINDS

try:
    event = ExternalEvent(kind=kind, payload=payload)
except ValueError as exc:
    logger.warning("Dropping invalid external event: %s", exc)
    event = None

When it happens

Trigger: Constructing `ExternalEvent(kind="...", payload="...")` with a kind string not in `_VALID_KINDS` — a typo, a custom kind invented by a producer, or a protocol change between producer and consumer versions.

Common situations: Hand-writing events emitted over the Unix socket; a producer plugin using a kind name from a different app version; renaming a kind on the producer side without updating the consumer.

Related errors

• External event payload must be a non-empty string
• Unknown external signal: {self.payload!r}; expected one of {
• External event kind must be one of {sorted(_VALID_KINDS)}; g
• Could not parse embedded resource block. Block expected eith
• {question_type} question {question_text!r} must not define '

AI-assisted analysis of langchain-ai/deepagents@a1af029e6e (2026-08-29). Data as JSON: /api/errors/fffafdae913633cd. Report an issue: GitHub.