langchain-ai/deepagents · error · ValueError

External event must be valid JSON: {exc.msg}

Error message

External event must be valid JSON: {exc.msg}

What it means

`decode_external_event` parses one newline-delimited JSON line from the external event transport. If `json.loads` fails, the malformed line is rejected with a `ValueError` that carries the JSON parser's message. This guards the event bus against corrupted, truncated, or non-JSON input written to the socket stream.

Source

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

    """Decode one newline-delimited JSON external event.

    Args:
        data: Raw JSON line.
        source: Transport-specific source label attached to the event.

    Returns:
        Parsed external event.

    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:

View on GitHub (pinned to a1af029e6e)

Solutions

1. Fix the producer to emit one complete JSON object per line terminated by `\n`.
2. Use `json.dumps` on the producer side instead of hand-built strings.
3. Validate the payload with a JSON linter/parser before writing to the socket.
4. Catch `ValueError` in the reader wrapper and skip/log the malformed line if resyncing is acceptable.

Example fix

// before
echo kind: noop, payload: hi > /tmp/deepagents/events-1234.sock

// after
echo '{"kind":"noop","payload":"hi"}' | socat - UNIX-CONNECT:/tmp/deepagents/events-1234.sock

import json

def emit_event(sock_line: bytes) -> bool:
    try:
        value = json.loads(sock_line)
    except json.JSONDecodeError:
        return False
    return isinstance(value, dict)  # also satisfies the object check

def is_json_object(data: bytes) -> bool:
    try:
        return isinstance(json.loads(data), dict)
    except (json.JSONDecodeError, UnicodeDecodeError):
        return False

try:
    event = decode_external_event(line, source=source)
except ValueError as exc:
    logger.warning("dropping malformed external event line: %s", exc)
    return None

When it happens

Trigger: A writer sends a line to the external event socket that is not valid JSON: truncated writes, concatenated objects without a newline separator, raw text/printf output, or binary bytes piped into the socket.

Common situations: Scripts `echo`-ing events with unquoted braces; a partial write from a crashed producer; piping command output directly into the event socket; an old producer version emitting a different serialization format.

Related errors

• External event must be a JSON object
• External event kind must be one of {sorted(_VALID_KINDS)}; g
• External event bypass must be a valid bypass tier: {exc}
• External event correlation_id must be a string when present
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex

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