{"record":{"id":"882120ca396c0f8c","repo":"langchain-ai/deepagents","slug":"external-event-kind-must-be-one-of-sorted-valid","errorCode":null,"errorMessage":"External event kind must be one of {sorted(_VALID_KINDS)}; got {kind!r}","messagePattern":"External event kind must be one of (.+?); got (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/event_bus.py","lineNumber":386,"sourceCode":"\n    Raises:\n        TypeError: If the envelope is not a JSON object.\n        ValueError: If any envelope field is missing, of the wrong type, or\n            otherwise invalid.\n    \"\"\"\n    try:\n        raw = json.loads(data)\n    except json.JSONDecodeError as exc:\n        msg = f\"External event must be valid JSON: {exc.msg}\"\n        raise ValueError(msg) from exc\n    if not isinstance(raw, dict):\n        msg = \"External event must be a JSON object\"\n        raise TypeError(msg)\n\n    kind = raw.get(\"kind\")\n    if kind not in _VALID_KINDS:\n        msg = f\"External event kind must be one of {sorted(_VALID_KINDS)}; got {kind!r}\"\n        raise ValueError(msg)\n\n    payload = raw.get(\"payload\")\n    if not isinstance(payload, str) or not payload.strip():\n        msg = \"External event payload must be a non-empty string\"\n        raise ValueError(msg)\n\n    bypass = raw.get(\"bypass\", BypassTier.QUEUED.value)\n    try:\n        bypass_tier = BypassTier(bypass)\n    except ValueError as exc:\n        msg = f\"External event bypass must be a valid bypass tier: {exc}\"\n        raise ValueError(msg) from exc\n\n    correlation_id = raw.get(\"correlation_id\")\n    if correlation_id is not None and not isinstance(correlation_id, str):\n        msg = \"External event correlation_id must be a string when present\"\n        raise ValueError(msg)\n","sourceCodeStart":368,"sourceCodeEnd":404,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/event_bus.py#L368-L404","documentation":"`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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Use one of the accepted kinds listed in the error message (`sorted(_VALID_KINDS)`).","Upgrade or downgrade dcode / the producer so both agree on the kind vocabulary.","Fix casing/typos in the producer's kind strings.","In the reader, catch `ValueError` and log rejected kinds to discover producer drift."],"exampleFix":"// before\n{\"kind\":\"interrupt_agent\",\"payload\":\"x\"}\n\n// after\n{\"kind\":\"noop\",\"payload\":\"x\"}   // use a kind from _VALID_KINDS\n","handlingStrategy":"validation","validationCode":"from deepagents_code.event_bus import _VALID_KINDS\n\ndef assert_known_kind(kind: str) -> None:\n    if kind not in _VALID_KINDS:\n        raise ValueError(f\"unknown kind {kind!r}; valid: {sorted(_VALID_KINDS)}\")\n","typeGuard":"def is_known_kind(kind) -> bool:\n    return isinstance(kind, str) and kind in _VALID_KINDS\n","tryCatchPattern":"try:\n    event = decode_external_event(data, source=source)\nexcept ValueError as exc:\n    logger.warning(\"rejected external event kind: %s\", exc)\n    return None\n","preventionTips":["Import the kind vocabulary from the package instead of hardcoding strings.","Keep producer and dcode versions in sync.","Add a unit test asserting every emitted kind is in `_VALID_KINDS`."],"tags":["json","event-bus","validation","schema"],"backgroundTag":"schema-validation-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}