{"record":{"id":"54e2b0ba78c7eaaf","repo":"666ghj/MiroFish","slug":"episode-episode-uuid-did-not-finish-within-time","errorCode":null,"errorMessage":"episode {episode_uuid} did not finish within {timeout}s","messagePattern":"episode (.+?) did not finish within (.+?)s","errorType":"exception","errorClass":"TimeoutError","httpStatus":null,"severity":"error","filePath":"backend/scripts/validate_zep_cloud_integration.py","lineNumber":298,"sourceCode":"            \"reason\": \"updater_not_confirmed_drained\",\n        }\n\n    client.graph.delete(graph_id)\n    return {\n        \"graph_deleted\": True,\n        \"graph_retained\": False,\n        \"reason\": \"validation_cleanup\",\n    }\n\n\ndef _wait_for_episode(client: Any, episode_uuid: str, timeout: int) -> Any:\n    deadline = time.monotonic() + timeout\n    while time.monotonic() < deadline:\n        episode = client.graph.episode.get(uuid_=episode_uuid)\n        if getattr(episode, \"processed\", False):\n            return episode\n        time.sleep(3)\n    raise TimeoutError(f\"episode {episode_uuid} did not finish within {timeout}s\")\n\n\ndef _list_batch_items(client: Any, batch_id: str, page_size: int = 3) -> tuple[list[Any], int]:\n    items: list[Any] = []\n    cursor: int | None = None\n    pages = 0\n    while True:\n        response = client.batch.list_items(batch_id=batch_id, limit=page_size, cursor=cursor)\n        pages += 1\n        items.extend(response.items or [])\n        next_cursor = response.next_cursor\n        if next_cursor is None:\n            return items, pages\n        if next_cursor == cursor:\n            raise RuntimeError(\"batch item cursor did not advance\")\n        cursor = next_cursor\n\n","sourceCodeStart":280,"sourceCodeEnd":316,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/scripts/validate_zep_cloud_integration.py#L280-L316","documentation":"Raised by _wait_for_episode in backend/scripts/validate_zep_cloud_integration.py when an ingested episode's processed flag is still False after polling client.graph.episode.get(uuid_=...) every 3 seconds until a monotonic deadline. Zep processes episodes asynchronously; until processed=True, derived facts/nodes/edges are not guaranteed present, so the script refuses to continue on incomplete data. It is a TimeoutError.","triggerScenarios":"Calling _add_and_wait with a timeout shorter than Zep Cloud's actual ingestion latency; running during Zep Cloud slowdowns; very large episodes; or an episode that failed server-side processing and will never flip processed (guaranteeing the timeout).","commonSituations":"Default wait too tight for the corpus size; Zep Cloud processing backlog; episode payload in a format that errors server-side; big documents extracting many entities.","solutions":["Increase the timeout passed to _add_and_wait (e.g. 60 -> 300 seconds) and rerun.","Inspect the episode in the Zep console: a processing error means fixing the payload and re-adding, not waiting longer.","Check the Zep Cloud status page for ingestion delays before assuming a code bug.","Split very large documents into smaller episodes so latency stays predictable."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    episode_uuid = _add_and_wait(client, graph_id, item, timeout=60)\nexcept TimeoutError:\n    episode = client.graph.episode.get(uuid_=episode_uuid)\n    if not getattr(episode, \"processed\", False):\n        logger.warning(\"episode still processing; extending wait\")\n    episode_uuid = _add_and_wait(client, graph_id, item, timeout=300)","preventionTips":["Size the wait timeout to corpus size: large episodes need minutes, not seconds.","Check the Zep Cloud console/status page before assuming a code bug.","Split very large documents into smaller episodes for predictable latency."],"tags":["zep","timeout","async-ingestion","polling","cloud-latency"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}