{"record":{"id":"e638fab599b9174c","repo":"666ghj/MiroFish","slug":"zep-item-name-pagination-cursor-did-not-advance","errorCode":null,"errorMessage":"Zep {item_name} pagination cursor did not advance for graph {graph_id}","messagePattern":"Zep (.+?) pagination cursor did not advance for graph (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"backend/app/utils/zep_paging.py","lineNumber":112,"sourceCode":"        if max_items is not None and len(all_items) >= max_items:\n            if len(all_items) > max_items:\n                all_items = all_items[:max_items]\n            logger.warning(\n                \"Zep %s pagination reached explicit max_items=%s for graph %s\",\n                item_name,\n                max_items,\n                graph_id,\n            )\n            break\n\n        next_cursor = _header_value(\n            getattr(response, \"headers\", None),\n            _NEXT_CURSOR_HEADER,\n        )\n        if next_cursor is None:\n            break\n        if next_cursor in seen_cursors or next_cursor == cursor:\n            raise RuntimeError(\n                f\"Zep {item_name} pagination cursor did not advance for graph {graph_id}\"\n            )\n        seen_cursors.add(next_cursor)\n        cursor = next_cursor\n\n    return all_items\n\n\ndef fetch_all_nodes(\n    client: Zep,\n    graph_id: str,\n    page_size: int = _DEFAULT_PAGE_SIZE,\n    max_items: int | None = None,\n    max_retries: int = _DEFAULT_MAX_RETRIES,\n    retry_delay: float = _DEFAULT_RETRY_DELAY,\n) -> list[Any]:\n    \"\"\"Fetch every graph node unless the caller supplies an explicit cap.\"\"\"\n","sourceCodeStart":94,"sourceCodeEnd":130,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/app/utils/zep_paging.py#L94-L130","documentation":"Raised by the generic pagination loop in backend/app/utils/zep_paging.py when the zep-next-cursor response header (read via _header_value) either equals the current cursor or was already seen in seen_cursors. This is an infinite-loop guard: without it the fetch would request the same page forever. It is a RuntimeError with an f-string message naming the item kind (node/edge) and graph_id, raised after at least one successful page request. Used by fetch_all_nodes / fetch_all_edges.","triggerScenarios":"Calling fetch_all_nodes or fetch_all_edges on a graph whose API responses repeat a zep-next-cursor value — server-side pagination anomaly, a proxy rewriting/duplicating headers, or concurrent graph mutation between pages making cursors unstable.","commonSituations":"Zep Cloud API behavior change (cursor format or reuse); stale zep-cloud SDK version mis-parsing the header; paginating while an updater/batch job is actively writing to the same graph.","solutions":["Retry the full fetch from page one — cursor state is per-call and transient stalls usually clear.","Stop concurrent writers (updaters, batch.process) before running full-graph fetches.","Upgrade the zep-cloud package to the latest version — cursor handling has changed across releases.","If reproducible on a quiesced graph, capture the raw headers and report to Zep support with the graph_id."],"exampleFix":null,"handlingStrategy":"retry","validationCode":null,"typeGuard":null,"tryCatchPattern":"for attempt in range(3):\n    try:\n        items = fetch_all_nodes(client, graph_id, page_size=50)\n        break\n    except RuntimeError as e:\n        if \"cursor did not advance\" not in str(e) or attempt == 2:\n            raise\n        time.sleep(2 ** attempt)  # restart from page 1","preventionTips":["Quiesce the graph before full fetches: stop updaters/batch writers first.","Use larger page_size to reduce cursor transitions (fewer chances to observe a loop).","Pin a known-good zep-cloud version and re-test pagination after SDK upgrades."],"tags":["zep","pagination","infinite-loop-guard","api-contract","runtime"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}