{"record":{"id":"e907c78690243cbc","repo":"langchain-ai/deepagents","slug":"external-event-bypass-must-be-a-valid-bypass-tier","errorCode":null,"errorMessage":"External event bypass must be a valid bypass tier: {exc}","messagePattern":"External event bypass must be a valid bypass tier: (.+?)","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/event_bus.py","lineNumber":398,"sourceCode":"        msg = \"External event must be a JSON object\"\n        raise TypeError(msg)\n\n    kind = raw.get(\"kind\")\n    if kind not in _VALID_KINDS:\n        msg = f\"External event kind must be one of {sorted(_VALID_KINDS)}; got {kind!r}\"\n        raise ValueError(msg)\n\n    payload = raw.get(\"payload\")\n    if not isinstance(payload, str) or not payload.strip():\n        msg = \"External event payload must be a non-empty string\"\n        raise ValueError(msg)\n\n    bypass = raw.get(\"bypass\", BypassTier.QUEUED.value)\n    try:\n        bypass_tier = BypassTier(bypass)\n    except ValueError as exc:\n        msg = f\"External event bypass must be a valid bypass tier: {exc}\"\n        raise ValueError(msg) from exc\n\n    correlation_id = raw.get(\"correlation_id\")\n    if correlation_id is not None and not isinstance(correlation_id, str):\n        msg = \"External event correlation_id must be a string when present\"\n        raise ValueError(msg)\n\n    return ExternalEvent(\n        kind=kind,\n        payload=payload,\n        source=source,\n        bypass=bypass_tier,\n        correlation_id=correlation_id,\n    )\n","sourceCodeStart":380,"sourceCodeEnd":412,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/event_bus.py#L380-L412","documentation":"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`.","triggerScenarios":"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.","commonSituations":"Producers written against an older/newer tier vocabulary; case mismatch between producer constant and enum value; numeric tier IDs used by custom integrations.","solutions":["Use the exact string value of a `BypassTier` member (the default `QUEUED` tier applies when `bypass` is omitted).","Import `BypassTier` from the package and send `BypassTier.YOUR_TIER.value`.","Align producer constants with the dcode version's enum definition.","Catch `ValueError` in the reader to log unsupported tier requests."],"exampleFix":"// before\n{\"kind\":\"noop\",\"payload\":\"x\",\"bypass\":\"URGENT\"}\n\n// after\n{\"kind\":\"noop\",\"payload\":\"x\",\"bypass\":\"queued\"}\n","handlingStrategy":"validation","validationCode":"from deepagents_code.event_bus import BypassTier\n\ndef assert_valid_bypass(value) -> None:\n    if value is None:\n        return\n    BypassTier(value)  # raises ValueError with the accepted values\n","typeGuard":"def is_valid_bypass(value) -> bool:\n    try:\n        BypassTier(value)\n        return True\n    except ValueError:\n        return False\n","tryCatchPattern":"try:\n    event = decode_external_event(data, source=source)\nexcept ValueError as exc:\n    logger.warning(\"invalid bypass tier in external event: %s\", exc)\n    return None\n","preventionTips":["Send `BypassTier.<MEMBER>.value`, never raw constants or numbers.","Omit `bypass` to accept the QUEUED default.","Pin producer constants to the dcode version's enum definition."],"tags":["json","event-bus","enum","validation"],"backgroundTag":"invalid-enum-value","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}