{"record":{"id":"8239800079091c30","repo":"666ghj/MiroFish","slug":"zep-batch-submission-batch-id-returned-an-incomp","errorCode":null,"errorMessage":"Zep batch {submission.batch_id} returned an incomplete item","messagePattern":"Zep batch (.+?) returned an incomplete item","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"backend/app/services/graph_builder.py","lineNumber":700,"sourceCode":"                f\"failed_items={len(failed_items)}; first_error={first_error}\"\n            )\n        if len(items) != submission.item_count:\n            raise RuntimeError(\n                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","sourceCodeStart":682,"sourceCodeEnd":718,"githubUrl":"https://github.com/666ghj/MiroFish/blob/b5b53acc57189a4a42e44a23e149dc655c98fe82/backend/app/services/graph_builder.py#L682-L718","documentation":"Raised by GraphBuilder._wait_for_batch while validating each item of a succeeded batch: after sorting items by sequence_index, any item whose status is not exactly 'succeeded', or whose episode_uuid is missing/empty, triggers this RuntimeError. Even though the batch overall reported success, at least one item did not produce a usable episode reference, so the pipeline refuses to return a partial UUID list.","triggerScenarios":"A batch item whose status is 'skipped' or another non-succeeded value at item level (note: 'skipped' is tolerated in the count check of error 23 but NOT here), or an item that succeeded but Zep returned no episode_uuid attribute. Usually a handful of items in an otherwise green batch.","commonSituations":"Zep skipping items it considers duplicates or empty while still marking the batch 'succeeded'; SDK version returning episode_uuid under a different attribute name; items with blank/degenerate text that Zep processes to nothing.","solutions":["List the batch items manually and inspect the offending item's status/error fields to learn why Zep did not fully succeed it.","Filter out empty or whitespace-only chunks before submission — they are the most common cause of per-item skips.","Upgrade the zep-cloud SDK if attribute names drifted; the code reads episode_uuid via getattr and None fails the check.","Resubmit only the incomplete items as a fresh batch and merge the resulting UUID lists."],"exampleFix":"# before\nchunks = raw_chunks\n# after\nchunks = [c.strip() for c in raw_chunks]\nchunks = [c for c in chunks if c]","handlingStrategy":"validation","validationCode":"chunks = [c for c in (c.strip() for c in chunks) if c]  # drop empty/blank chunks that Zep skips","typeGuard":null,"tryCatchPattern":"try:\n    uuids = builder._wait_for_batch(submission)\nexcept RuntimeError as e:\n    if 'incomplete item' in str(e):\n        bad = [i for i in builder._list_batch_items(submission.batch_id)\n               if getattr(i, 'status', None) != 'succeeded' or not getattr(i, 'episode_uuid', None)]\n        resubmit([original_chunk_for(i) for i in bad])\n    else:\n        raise","preventionTips":["Strip and filter empty chunks before submission.","Keep a mapping from sequence_index to source chunk so failed items can be resubmitted individually.","Keep the zep-cloud SDK current so item attributes parse as expected."],"tags":["zep","batch-api","validation","episode-uuid","ingestion"],"backgroundTag":null,"analyzedSha":"b5b53acc57189a4a42e44a23e149dc655c98fe82","analyzedAt":"2026-08-14T22:29:33.146Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}