{"record":{"id":"85e767f5e5f5fbba","repo":"666ghj/MiroFish","slug":"zep-batch-submission-batch-id-returned-mismatche","errorCode":null,"errorMessage":"Zep batch {submission.batch_id} returned mismatched episode UUIDs","messagePattern":"Zep batch (.+?) returned mismatched episode UUIDs","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"backend/app/services/graph_builder.py","lineNumber":704,"sourceCode":"                f\"Zep batch {submission.batch_id} contains {len(items)} items, \"\n                f\"expected {submission.item_count}\"\n            )\n\n        ordered_items = sorted(\n            items,\n            key=lambda item: getattr(item, \"sequence_index\", 0) or 0,\n        )\n        episode_uuids: List[str] = []\n        for item in ordered_items:\n            item_status = getattr(item, \"status\", None)\n            episode_uuid = getattr(item, \"episode_uuid\", None)\n            source_uuid = getattr(item, \"source_uuid\", None)\n            if item_status != \"succeeded\" or not episode_uuid:\n                raise RuntimeError(\n                    f\"Zep batch {submission.batch_id} returned an incomplete item\"\n                )\n            if source_uuid and source_uuid != episode_uuid:\n                raise RuntimeError(\n                    f\"Zep batch {submission.batch_id} returned mismatched episode UUIDs\"\n                )\n            episode_uuids.append(episode_uuid)\n\n        if progress_callback:\n            progress_callback(\n                t(\n                    'progress.processingComplete',\n                    completed=len(episode_uuids),\n                    total=submission.item_count,\n                ),\n                1.0,\n            )\n        return episode_uuids\n    \n    def _wait_for_episodes(\n        self,\n        episode_uuids: List[str],","sourceCodeStart":686,"sourceCodeEnd":722,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/app/services/graph_builder.py#L686-L722","documentation":"Raised by GraphBuilder._wait_for_batch during per-item validation: for a succeeded item that has a source_uuid, that source_uuid must equal the item's episode_uuid. Zep echoes back the client-supplied source UUID; a mismatch means the server re-associated the item with a different episode than the one the client declared (e.g. dedup merged it into an existing episode), which would corrupt the builder's UUID bookkeeping.","triggerScenarios":"Submitting items with explicit source_uuid values that collide with already-ingested episodes in the same graph, so Zep deduplicates/merges them into an existing episode and returns a different episode_uuid; or re-running ingestion of the same content into the same graph-id combination twice.","commonSituations":"Rebuilding a graph without a new graph-id, so previous episodes exist and Zep dedupes new items onto them; retrying a partially failed ingestion run with the same source UUIDs; switching a project between shared and per-project graphs while reusing source UUIDs.","solutions":["Use a fresh graph (new graph_id) for a full rebuild instead of re-ingesting into the existing one.","Regenerate unique source_uuid values (e.g. uuid4-derived, content-hash + run-id) for every retry so dedup cannot merge across runs.","Before resubmitting, search the graph (client.graph.episode/search) for the source_uuid to check whether it already exists.","If Zep should never merge, review whether your plan/config enables dedup and disable it for this workflow."],"exampleFix":"# before\nsource_uuid = content_hash  # stable across runs -> dedup merges\n# after\nimport uuid\nsource_uuid = f'{run_id}:{content_hash}'  # unique per run","handlingStrategy":"validation","validationCode":"def make_source_uuid(run_id: str, content_hash: str) -> str:\n    return f'{run_id}:{content_hash}'  # unique per ingestion run, dedup-proof","typeGuard":null,"tryCatchPattern":"try:\n    uuids = builder._wait_for_batch(submission)\nexcept RuntimeError as e:\n    if 'mismatched episode UUIDs' in str(e):\n        # episodes were deduped onto an existing graph; rebuild into a fresh graph_id\n        raise RuntimeError('re-ingest into a new graph or regenerate source UUIDs') from e\n    raise","preventionTips":["Use a new graph_id for full rebuilds.","Make source_uuid unique per run (run-id + content hash), never a bare stable hash.","Before re-ingesting, search the graph for existing source UUIDs."],"tags":["zep","batch-api","uuid","dedup","data-integrity"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}