langchain-ai/deepagents · error · ValueError

PendingNotification.key must be non-empty

Error message

PendingNotification.key must be non-empty

What it means

`PendingNotification` dataclass validation in `__post_init__` requires a non-empty `key`, since the key identifies the notification for deduplication and registry lookup. An empty (or missing) key raises a `ValueError` immediately at construction.

Source

Thrown at libs/code/deepagents_code/notifications.py:122

    May contain install instructions, links, or version info.
    """

    actions: tuple[NotificationAction, ...]
    """Available actions, rendered as rows in the modal."""

    payload: Payload
    """Kind-specific typed data consumed by the action dispatcher."""

    def __post_init__(self) -> None:
        """Enforce basic invariants at construction time.

        Raises:
            ValueError: If `key` is empty, `actions` is empty, or more
                than one action is marked `primary=True`.
        """
        if not self.key:
            msg = "PendingNotification.key must be non-empty"
            raise ValueError(msg)
        if not self.actions:
            msg = f"PendingNotification {self.key!r} must declare at least one action"
            raise ValueError(msg)
        primaries = sum(1 for a in self.actions if a.primary)
        if primaries > 1:
            msg = (
                f"PendingNotification {self.key!r} has {primaries} primary actions; "
                "at most one is allowed"
            )
            raise ValueError(msg)


class NotificationRegistry:
    """In-memory store of pending notifications.

    Instance-scoped (one per app) so test apps don't pollute each other.
    Owns the bidirectional key-to-toast-identity binding so callers
    cannot accidentally desynchronize the click-routing indices.

View on GitHub (pinned to a1af029e6e)

Solutions

1. Supply a stable, unique key at construction, e.g. derived from the event id
2. Skip constructing the notification when the source id is missing, logging instead
3. Guard with `if not event_id: return` before creating the PendingNotification

Example fix

// before
note = PendingNotification(key=event.get("id", ""), ...)
// after
if not (event_id := event.get("id")):
    return
note = PendingNotification(key=event_id, ...)

if not key:
    raise ValueError("Cannot create PendingNotification with an empty key")

def has_key(d: dict[str, object]) -> TypeGuard[dict[str, object]]:
    return isinstance(d.get("id"), str) and bool(d["id"])

try:
    note = PendingNotification(key=key, actions=actions)
except ValueError as e:
    logging.warning("dropping notification: %s", e)

When it happens

Trigger: Constructing `PendingNotification(key="")` or `key=None`, often when the key is built from a variable that ended up empty (unresolved template, missing field in source data).

Common situations: Building notifications from upstream payloads where the id field is absent; string formatting that produced ""; forgetting to set a default key.

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

• PendingNotification {self.key!r} must declare at least one a
• PendingNotification {self.key!r} has {primaries} primary act
• `unreadable_reason` implies the token is not usable; `logged
• `expires_at` must be set when `logged_in` is True.
• `expires_at` is only meaningful when `logged_in` is True.

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