666ghj/MiroFish · error · RuntimeError

artifact cursor did not advance

Error message

artifact cursor did not advance

What it means

Raised by _raw_pages in backend/scripts/validate_zep_cloud_integration.py when the zep-next-cursor response header equals the current cursor or reappears in the seen set. _raw_pages deliberately walks the with_raw_response API (response.data plus response.headers) to cross-check the production fetch_all_* helpers, so this error means the raw cursor traversal itself would not terminate. It is a RuntimeError.

Source

Thrown at backend/scripts/validate_zep_cloud_integration.py:333

def _raw_pages(api_call: Any, graph_id: str, page_size: int = 2) -> tuple[list[Any], int]:
    items: list[Any] = []
    cursor: str | None = None
    pages = 0
    seen: set[str] = set()
    while True:
        kwargs: dict[str, Any] = {"limit": page_size}
        if cursor:
            kwargs["cursor"] = cursor
        response = api_call(graph_id, **kwargs)
        pages += 1
        items.extend(list(response.data or []))
        next_cursor = response.headers.get("zep-next-cursor")
        if not next_cursor:
            return items, pages
        if next_cursor == cursor or next_cursor in seen:
            raise RuntimeError("artifact cursor did not advance")
        seen.add(next_cursor)
        cursor = next_cursor


def _edge_view(edge: Any, node_names: dict[str, str]) -> dict[str, Any]:
    return {
        "uuid": _uuid(edge),
        "name": edge.name,
        "fact": edge.fact,
        "source": node_names.get(edge.source_node_uuid, edge.source_node_uuid),
        "target": node_names.get(edge.target_node_uuid, edge.target_node_uuid),
        "created_at": edge.created_at,
        "valid_at": edge.valid_at,
        "invalid_at": edge.invalid_at,
        "expired_at": edge.expired_at,
        "attributes": edge.attributes or {},
    }

View on GitHub (pinned to b5b53acc57)

Solutions

1. Retry the run — transient header anomalies are usually not stable.
2. Upgrade zep-cloud to the latest version.
3. If a proxy sits between the script and Zep Cloud, bypass it and compare results.
4. Report persistent cases to Zep support with graph_id and the offending cursor values.

try:
    items, pages = _raw_pages(api_call, graph_id, page_size=2)
except RuntimeError as e:
    if "artifact cursor did not advance" in str(e):
        time.sleep(5)
        items, pages = _raw_pages(api_call, graph_id, page_size=2)
    else:
        raise

When it happens

Trigger: Paginating graph.node/edge.with_raw_response.get_by_graph_id with limit=page_size when the server (or an intermediate proxy that rewrites headers) returns a duplicated zep-next-cursor value across pages.

Common situations: A corporate proxy or gateway normalizing/duplicating response headers; zep-cloud SDK version parsing headers differently; server-side pagination regression on Zep Cloud.

Related errors

• Zep batch list cursor did not advance
• Zep batch {batch_id} item cursor did not advance
• Zep {item_name} pagination cursor did not advance for graph
• batch item cursor did not advance
• Zep batch {submission.batch_id} contains {len(items)} items,

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