666ghj/MiroFish · error · RuntimeError

graph.add returned no episode UUID

Error message

graph.add returned no episode UUID

What it means

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_).

Source

Thrown at backend/scripts/validate_zep_cloud_integration.py:401

            "source": "mirofish_zep_deep_validation",
            "phase": item.phase,
            "sequence": index,
        },
    )


def _add_and_wait(client: Any, graph_id: str, item: SourceEpisode, timeout: int) -> str:
    episode = client.graph.add(
        graph_id=graph_id,
        type=item.data_type,
        data=item.data,
        created_at=item.created_at,
        source_description="MiroFish temporal Zep Cloud validation update",
        metadata={"source": "mirofish_zep_deep_validation", "phase": item.phase},
    )
    episode_uuid = _uuid(episode)
    if not episode_uuid:
        raise RuntimeError("graph.add returned no episode UUID")
    _wait_for_episode(client, episode_uuid, timeout)
    return episode_uuid


def _activities() -> Iterable[AgentActivity]:
    return [
        AgentActivity(
            platform="twitter",
            agent_id=101,
            agent_name="陈屿",
            action_type="CREATE_POST",
            action_args={"content": "海城市新总部今天启用，智巡平台商业服务正常运行。"},
            round_num=1,
            timestamp="2026-07-01T09:00:00Z",
        ),
        AgentActivity(
            platform="twitter",
            agent_id=102,

View on GitHub (pinned to b5b53acc57)

Solutions

1. Upgrade (or pin) the zep-cloud package to a version compatible with the current API and rerun.
2. Debug once by printing type(episode) and vars(episode) to see the actual field names.
3. If using a mock client in tests, make it return an object with uuid_ set.

def episode_has_uuid(episode: Any) -> bool:
    return bool(getattr(episode, "uuid_", None) or getattr(episode, "uuid", None))

try:
    episode_uuid = _add_and_wait(client, graph_id, item, timeout)
except RuntimeError as e:
    if "no episode UUID" in str(e):
        logger.error("SDK/API shape mismatch on graph.add")
        raise  # version issue: fix environment, do not retry
    raise

When it happens

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

Common situations: Version drift between the zep-cloud SDK and the Zep Cloud API; test doubles mimicking the client without replicating uuid_.

Related errors

• batch.create returned no batch_id
• Zep {item_name} pagination cursor did not advance for graph
• batch item cursor did not advance
• Graph {graph_id} is in use by active consumer(s): {', '.join
• Persisted Zep batch does not match the current graph input

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