langchain-ai/deepagents · error · ValueError

Unknown external signal: {self.payload!r}; expected one of {

Error message

Unknown external signal: {self.payload!r}; expected one of {sorted(_VALID_SIGNALS)}

What it means

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.

Source

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

        """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.
    """

    async def start(
        self,
        sink: Callable[[ExternalEvent], Awaitable[None]],
    ) -> None:
        """Start forwarding events to `sink`.

        Args:
            sink: Async callback that receives parsed external events.
        """

View on GitHub (pinned to a1af029e6e)

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.

Example fix

// before
ExternalEvent(kind="signal", payload="restart-now")
// after
ExternalEvent(kind="signal", payload="reload")  # one of sorted(_VALID_SIGNALS)

Defensive patterns

Strategy: validation

Validate before calling

from deepagents_code.event_bus import _VALID_SIGNALS

def safe_signal(payload: str):
    if payload.strip().lower() not in _VALID_SIGNALS:
        return None
    return ExternalEvent(kind="signal", payload=payload)

Type guard

def is_known_signal(payload: str) -> bool:
    return payload.strip().lower() in _VALID_SIGNALS

Try / catch

try:
    event = ExternalEvent(kind="signal", payload=name)
except ValueError as exc:
    logger.warning("Unknown signal dropped: %s", exc)
    event = None

Prevention

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.

When it happens

Trigger: Constructing `ExternalEvent(kind="signal", payload="<unknown-name>")` — misspelled signal, extra characters around the name, or a signal name from a different app version.

Common situations: 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.

Related errors

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