langchain-ai/deepagents · error · ValueError

External event bypass must be a valid bypass tier: {exc}

Error message

External event bypass must be a valid bypass tier: {exc}

What it means

The optional `bypass` field selects a `BypassTier` that controls queue priority for the event. `decode_external_event` constructs `BypassTier(bypass)`; if the value is not a valid tier, it re-raises with a `ValueError` wrapping the enum's own message. Unset defaults to `BypassTier.QUEUED`.

Source

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

        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:
        msg = f"External event bypass must be a valid bypass tier: {exc}"
        raise ValueError(msg) from exc

    correlation_id = raw.get("correlation_id")
    if correlation_id is not None and not isinstance(correlation_id, str):
        msg = "External event correlation_id must be a string when present"
        raise ValueError(msg)

    return ExternalEvent(
        kind=kind,
        payload=payload,
        source=source,
        bypass=bypass_tier,
        correlation_id=correlation_id,
    )

View on GitHub (pinned to a1af029e6e)

Solutions

1. Use the exact string value of a `BypassTier` member (the default `QUEUED` tier applies when `bypass` is omitted).
2. Import `BypassTier` from the package and send `BypassTier.YOUR_TIER.value`.
3. Align producer constants with the dcode version's enum definition.
4. Catch `ValueError` in the reader to log unsupported tier requests.

Example fix

// before
{"kind":"noop","payload":"x","bypass":"URGENT"}

// after
{"kind":"noop","payload":"x","bypass":"queued"}

from deepagents_code.event_bus import BypassTier

def assert_valid_bypass(value) -> None:
    if value is None:
        return
    BypassTier(value)  # raises ValueError with the accepted values

def is_valid_bypass(value) -> bool:
    try:
        BypassTier(value)
        return True
    except ValueError:
        return False

try:
    event = decode_external_event(data, source=source)
except ValueError as exc:
    logger.warning("invalid bypass tier in external event: %s", exc)
    return None

When it happens

Trigger: Sending `"bypass":"URGENT"`, `"bypass":1`, `"bypass":"high"`, or any value not matching a `BypassTier` member value; sending the Python enum object (which `json.dumps` serializes unexpectedly) instead of its string value.

Common situations: Producers written against an older/newer tier vocabulary; case mismatch between producer constant and enum value; numeric tier IDs used by custom integrations.

Understand the failure class

Background: Invalid enum value errors: "Unknown type", "Invalid scope", "must be one of" — when a string is not on the library's allowed list — this error's family across 23 libraries.

Related errors

• External event must be valid JSON: {exc.msg}
• External event kind must be one of {sorted(_VALID_KINDS)}; g
• External event correlation_id must be a string when present
• Invalid {SERVER_ENV_PREFIX}ALLOW_FS_TOOLS value: {raw!r}; ex
• Invalid MCP config at {mcp_config_path}: {exc}

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