{"record":{"id":"ff52dec1ddd0850e","repo":"langchain-ai/deepagents","slug":"external-event-correlation-id-must-be-a-string-whe","errorCode":null,"errorMessage":"External event correlation_id must be a string when present","messagePattern":"External event correlation_id must be a string when present","errorType":"validation","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"libs/code/deepagents_code/event_bus.py","lineNumber":403,"sourceCode":"        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":385,"sourceCodeEnd":412,"githubUrl":"https://github.com/langchain-ai/deepagents/blob/a1af029e6e73cb17c36bff823d227747b28e91e1/libs/code/deepagents_code/event_bus.py#L385-L412","documentation":"`correlation_id` is an optional string used to tie related external events together. `decode_external_event` allows it to be absent or null but rejects any other type (number, bool, object, array) with a `ValueError`. This keeps downstream correlation logic working with a consistent string type.","triggerScenarios":"Sending `\"correlation_id\":12345`, a UUID object serialized as a JSON object, a boolean, or a nested value instead of a string (or null/omitted).","commonSituations":"Producers using auto-increment integer IDs; UUID libraries serializing to objects instead of `str(uuid)`; shell scripts interpolating raw numbers without quotes.","solutions":["Serialize the correlation id as a string, e.g. `str(uuid.uuid4())`.","Omit `correlation_id` entirely when no correlation is needed.","Coerce numeric IDs to strings on the producer side.","Catch `ValueError` in reader diagnostics to flag producers sending typed ids."],"exampleFix":"// before\n{\"kind\":\"noop\",\"payload\":\"x\",\"correlation_id\":12345}\n\n// after\n{\"kind\":\"noop\",\"payload\":\"x\",\"correlation_id\":\"12345\"}\n","handlingStrategy":"validation","validationCode":"def assert_correlation_id_ok(value) -> None:\n    if value is not None and not isinstance(value, str):\n        raise ValueError(\"correlation_id must be a string when present\")\n","typeGuard":"def is_valid_correlation_id(value) -> bool:\n    return value is None or isinstance(value, str)\n","tryCatchPattern":"try:\n    event = decode_external_event(data, source=source)\nexcept ValueError as exc:\n    logger.warning(\"external event rejected (correlation_id): %s\", exc)\n    return None\n","preventionTips":["Use `str(uuid4())` or stringified ids for correlation ids.","Omit the field rather than sending null-like non-strings.","Quote numeric ids in shell producers."],"tags":["json","event-bus","validation"],"backgroundTag":"schema-validation-failed","analyzedSha":"a1af029e6e73cb17c36bff823d227747b28e91e1","analyzedAt":"2026-08-29T11:43:24.718Z","schemaVersion":2},"datasetVersion":"2026-08-29T12:17:43.993Z"}