langchain-ai/deepagents · error · ValueError

External event kind must be one of {sorted(_VALID_KINDS)}; g

Error message

External event kind must be one of {sorted(_VALID_KINDS)}; got {kind!r}

What it means

`decode_external_event` validates the `kind` field against `_VALID_KINDS`, the set of event kinds the bus recognizes. Unknown or missing kinds are rejected with a `ValueError` listing the accepted values. This keeps the external event surface closed to accidental or hostile signals.

Source

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

    Raises:
        TypeError: If the envelope is not a JSON object.
        ValueError: If any envelope field is missing, of the wrong type, or
            otherwise invalid.
    """
    try:
        raw = json.loads(data)
    except json.JSONDecodeError as exc:
        msg = f"External event must be valid JSON: {exc.msg}"
        raise ValueError(msg) from exc
    if not isinstance(raw, dict):
        msg = "External event must be a JSON object"
        raise TypeError(msg)

    kind = raw.get("kind")
    if kind not in _VALID_KINDS:
        msg = f"External event kind must be one of {sorted(_VALID_KINDS)}; got {kind!r}"
        raise ValueError(msg)

    payload = raw.get("payload")
    if not isinstance(payload, str) or not payload.strip():
        msg = "External event payload must be a non-empty string"
        raise ValueError(msg)

    bypass = raw.get("bypass", BypassTier.QUEUED.value)
    try:
        bypass_tier = BypassTier(bypass)
    except ValueError as exc:
        msg = f"External event bypass must be a valid bypass tier: {exc}"
        raise ValueError(msg) from exc

    correlation_id = raw.get("correlation_id")
    if correlation_id is not None and not isinstance(correlation_id, str):
        msg = "External event correlation_id must be a string when present"
        raise ValueError(msg)

View on GitHub (pinned to a1af029e6e)

Solutions

1. Use one of the accepted kinds listed in the error message (`sorted(_VALID_KINDS)`).
2. Upgrade or downgrade dcode / the producer so both agree on the kind vocabulary.
3. Fix casing/typos in the producer's kind strings.
4. In the reader, catch `ValueError` and log rejected kinds to discover producer drift.

Example fix

// before
{"kind":"interrupt_agent","payload":"x"}

// after
{"kind":"noop","payload":"x"}   // use a kind from _VALID_KINDS

from deepagents_code.event_bus import _VALID_KINDS

def assert_known_kind(kind: str) -> None:
    if kind not in _VALID_KINDS:
        raise ValueError(f"unknown kind {kind!r}; valid: {sorted(_VALID_KINDS)}")

def is_known_kind(kind) -> bool:
    return isinstance(kind, str) and kind in _VALID_KINDS

try:
    event = decode_external_event(data, source=source)
except ValueError as exc:
    logger.warning("rejected external event kind: %s", exc)
    return None

When it happens

Trigger: Sending `kind` missing entirely, a typo (`"Noop"` vs accepted value), or a kind from an older/newer producer version that is not in `_VALID_KINDS`.

Common situations: Producer and dcode versions out of sync so the producer emits a kind the bus no longer accepts; hand-written test scripts inventing kinds; case-sensitivity mistakes in shell one-liners.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• Unknown external event kind: {self.kind!r}
• External event must be valid JSON: {exc.msg}
• External event must be a JSON object
• External event bypass must be a valid bypass tier: {exc}
• External event correlation_id must be a string when present

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