666ghj/MiroFish · error · TimeoutError

episode {episode_uuid} did not finish within {timeout}s

Error message

episode {episode_uuid} did not finish within {timeout}s

What it means

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.

Source

Thrown at backend/scripts/validate_zep_cloud_integration.py:298

            "reason": "updater_not_confirmed_drained",
        }

    client.graph.delete(graph_id)
    return {
        "graph_deleted": True,
        "graph_retained": False,
        "reason": "validation_cleanup",
    }


def _wait_for_episode(client: Any, episode_uuid: str, timeout: int) -> Any:
    deadline = time.monotonic() + timeout
    while time.monotonic() < deadline:
        episode = client.graph.episode.get(uuid_=episode_uuid)
        if getattr(episode, "processed", False):
            return episode
        time.sleep(3)
    raise TimeoutError(f"episode {episode_uuid} did not finish within {timeout}s")


def _list_batch_items(client: Any, batch_id: str, page_size: int = 3) -> tuple[list[Any], int]:
    items: list[Any] = []
    cursor: int | None = None
    pages = 0
    while True:
        response = client.batch.list_items(batch_id=batch_id, limit=page_size, cursor=cursor)
        pages += 1
        items.extend(response.items or [])
        next_cursor = response.next_cursor
        if next_cursor is None:
            return items, pages
        if next_cursor == cursor:
            raise RuntimeError("batch item cursor did not advance")
        cursor = next_cursor

View on GitHub (pinned to b5b53acc57)

Solutions

1. Increase the timeout passed to _add_and_wait (e.g. 60 -> 300 seconds) and rerun.
2. Inspect the episode in the Zep console: a processing error means fixing the payload and re-adding, not waiting longer.
3. Check the Zep Cloud status page for ingestion delays before assuming a code bug.
4. Split very large documents into smaller episodes so latency stays predictable.

try:
    episode_uuid = _add_and_wait(client, graph_id, item, timeout=60)
except TimeoutError:
    episode = client.graph.episode.get(uuid_=episode_uuid)
    if not getattr(episode, "processed", False):
        logger.warning("episode still processing; extending wait")
    episode_uuid = _add_and_wait(client, graph_id, item, timeout=300)

When it happens

Trigger: 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).

Common situations: 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.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Zep batch {submission.batch_id} did not finish within {timeo
• Zep episode processing timed out with {len(pending_episodes)
• Zep simulation ingestion timed out with {len(pending)} episo
• 模拟仍在停止中，图谱写入未在 {wait_timeout:.0f}s 内完成
• Zep updater worker did not stop within {join_timeout:.0f}s

AI-assisted analysis of 666ghj/MiroFish@b5b53acc57 (2026-08-14). Data as JSON: /api/errors/54e2b0ba78c7eaaf. Report an issue: GitHub.