{"record":{"id":"bf5d33ed49198671","repo":"langchain-ai/deepagents","slug":"unknown-external-signal-self-payload-r-expecte","errorCode":null,"errorMessage":"Unknown external signal: {self.payload!r}; expected one of {sorted(_VALID_SIGNALS)}","messagePattern":"Unknown external signal: (.+?); expected one of (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/event_bus.py","lineNumber":84,"sourceCode":"        \"\"\"Validate invariants for direct construction.\n\n        Raises:\n            ValueError: If `kind` is not a known kind, the payload is empty\n                or whitespace-only, or the kind is `\"signal\"` but the payload\n                is not a recognized signal name.\n        \"\"\"\n        if self.kind not in _VALID_KINDS:\n            msg = f\"Unknown external event kind: {self.kind!r}\"\n            raise ValueError(msg)\n        if not self.payload or not self.payload.strip():\n            msg = \"External event payload must be a non-empty string\"\n            raise ValueError(msg)\n        if self.kind == \"signal\" and self.payload.strip().lower() not in _VALID_SIGNALS:\n            msg = (\n                f\"Unknown external signal: {self.payload!r}; \"\n                f\"expected one of {sorted(_VALID_SIGNALS)}\"\n            )\n            raise ValueError(msg)\n\n\nclass EventSource(Protocol):\n    \"\"\"Source of external events for the Textual app.\n\n    Implementations must be safe to `stop()` even when `start()` failed\n    partway through; the app always invokes `stop()` from a `finally` block.\n    \"\"\"\n\n    async def start(\n        self,\n        sink: Callable[[ExternalEvent], Awaitable[None]],\n    ) -> None:\n        \"\"\"Start forwarding events to `sink`.\n\n        Args:\n            sink: Async callback that receives parsed external events.\n        \"\"\"","sourceCodeStart":66,"sourceCodeEnd":102,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/event_bus.py#L66-L102","documentation":"When an event's kind is \"signal\", the payload must name one of the recognized signals in `_VALID_SIGNALS` (compared case-insensitively via `payload.strip().lower()`). An unrecognized signal name is rejected with this ValueError, which lists the valid options, so the app never dispatches a signal it has no handler for.","triggerScenarios":"Constructing `ExternalEvent(kind=\"signal\", payload=\"<unknown-name>\")` — misspelled signal, extra characters around the name, or a signal name from a different app version.","commonSituations":"Socket clients sending ad-hoc signal strings; documentation drift after a signal was renamed; automation scripts guessing signal names instead of reading the enumerated set.","solutions":["Use one of the signals listed in the error message (sorted `_VALID_SIGNALS`).","Check `_VALID_SIGNALS` in event_bus.py for canonical names and match them (case-insensitive).","Update producer/automation scripts to current signal names after upgrading the library.","If a new signal is needed, add it to `_VALID_SIGNALS` plus a handler in the app."],"exampleFix":"// before\nExternalEvent(kind=\"signal\", payload=\"restart-now\")\n// after\nExternalEvent(kind=\"signal\", payload=\"reload\")  # one of sorted(_VALID_SIGNALS)","handlingStrategy":"validation","validationCode":"from deepagents_code.event_bus import _VALID_SIGNALS\n\ndef safe_signal(payload: str):\n    if payload.strip().lower() not in _VALID_SIGNALS:\n        return None\n    return ExternalEvent(kind=\"signal\", payload=payload)","typeGuard":"def is_known_signal(payload: str) -> bool:\n    return payload.strip().lower() in _VALID_SIGNALS","tryCatchPattern":"try:\n    event = ExternalEvent(kind=\"signal\", payload=name)\nexcept ValueError as exc:\n    logger.warning(\"Unknown signal dropped: %s\", exc)\n    event = None","preventionTips":["Reference the signal names from the error message / `_VALID_SIGNALS`, never guessed strings.","Update automation scripts when upgrading the library.","Add new signals to `_VALID_SIGNALS` plus a handler rather than emitting ad-hoc names."],"tags":["event-bus","validation","signal","input-error"],"backgroundTag":"unknown-signal-name","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}