{"record":{"id":"4dc15ccba40c3a1c","repo":"666ghj/MiroFish","slug":"graph-add-returned-no-episode-uuid","errorCode":null,"errorMessage":"graph.add returned no episode UUID","messagePattern":"graph\\.add returned no episode UUID","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"backend/scripts/validate_zep_cloud_integration.py","lineNumber":401,"sourceCode":"            \"source\": \"mirofish_zep_deep_validation\",\n            \"phase\": item.phase,\n            \"sequence\": index,\n        },\n    )\n\n\ndef _add_and_wait(client: Any, graph_id: str, item: SourceEpisode, timeout: int) -> str:\n    episode = client.graph.add(\n        graph_id=graph_id,\n        type=item.data_type,\n        data=item.data,\n        created_at=item.created_at,\n        source_description=\"MiroFish temporal Zep Cloud validation update\",\n        metadata={\"source\": \"mirofish_zep_deep_validation\", \"phase\": item.phase},\n    )\n    episode_uuid = _uuid(episode)\n    if not episode_uuid:\n        raise RuntimeError(\"graph.add returned no episode UUID\")\n    _wait_for_episode(client, episode_uuid, timeout)\n    return episode_uuid\n\n\ndef _activities() -> Iterable[AgentActivity]:\n    return [\n        AgentActivity(\n            platform=\"twitter\",\n            agent_id=101,\n            agent_name=\"陈屿\",\n            action_type=\"CREATE_POST\",\n            action_args={\"content\": \"海城市新总部今天启用，智巡平台商业服务正常运行。\"},\n            round_num=1,\n            timestamp=\"2026-07-01T09:00:00Z\",\n        ),\n        AgentActivity(\n            platform=\"twitter\",\n            agent_id=102,","sourceCodeStart":383,"sourceCodeEnd":419,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/scripts/validate_zep_cloud_integration.py#L383-L419","documentation":"Raised by _add_and_wait in backend/scripts/validate_zep_cloud_integration.py when client.graph.add succeeds but _uuid() (which tries uuid_ then uuid attributes) returns an empty string — the returned episode object exposes neither attribute, leaving no handle to poll for processing. It is a RuntimeError guarding against an unexpected SDK/API response shape (normally graph.add returns the created episode with uuid_).","triggerScenarios":"graph.add returning a response lacking uuid_ — typically after a zep-cloud SDK upgrade renamed the field, an API response-envelope change, or a mocked/stubbed client in tests returning an incomplete object.","commonSituations":"Version drift between the zep-cloud SDK and the Zep Cloud API; test doubles mimicking the client without replicating uuid_.","solutions":["Upgrade (or pin) the zep-cloud package to a version compatible with the current API and rerun.","Debug once by printing type(episode) and vars(episode) to see the actual field names.","If using a mock client in tests, make it return an object with uuid_ set."],"exampleFix":null,"handlingStrategy":"try-catch","validationCode":null,"typeGuard":"def episode_has_uuid(episode: Any) -> bool:\n    return bool(getattr(episode, \"uuid_\", None) or getattr(episode, \"uuid\", None))","tryCatchPattern":"try:\n    episode_uuid = _add_and_wait(client, graph_id, item, timeout)\nexcept RuntimeError as e:\n    if \"no episode UUID\" in str(e):\n        logger.error(\"SDK/API shape mismatch on graph.add\")\n        raise  # version issue: fix environment, do not retry\n    raise","preventionTips":["Pin a known-good zep-cloud version and upgrade deliberately.","Smoke-test graph.add after any SDK upgrade before running long validations.","Keep test doubles faithful: mocked episodes must expose uuid_."],"tags":["zep","sdk-compatibility","api-contract","version-drift","runtime"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}