666ghj/MiroFish · error · RuntimeError

Zep batch {batch_id} item submission is unconfirmed; the dra

Error message

Zep batch {batch_id} item submission is unconfirmed; the draft was not processed or replayed

What it means

RuntimeError in submit_document_batch's item-add loop: client.batch.add failed with a retryable error, so the code reconciled by listing the batch's items and checking that the recovered set is exactly expected_item_count items with sequence_index covering range(expected_item_count). If the recovered items are incomplete or out of sequence, the draft was neither fully processed nor safely replayable, so continuing risks duplicated or missing episodes — it refuses.

Source

Thrown at backend/app/services/graph_builder.py:512

            except Exception as e:
                if progress_callback:
                    progress_callback(t('progress.batchFailed', batch=batch_num, error=str(e)), 0)
                if is_retryable_zep_error(e):
                    recovered_items = self._reconcile_batch_item_count(
                        batch_id,
                        expected_item_count,
                    )
                    recovered_indexes = {
                        getattr(item, "sequence_index", None)
                        for item in recovered_items
                    }
                    if (
                        len(recovered_items) == expected_item_count
                        and recovered_indexes == set(range(expected_item_count))
                    ):
                        item_details = recovered_items[i:expected_item_count]
                    else:
                        raise RuntimeError(
                            f"Zep batch {batch_id} item submission is unconfirmed; "
                            "the draft was not processed or replayed"
                        ) from e
                else:
                    raise RuntimeError(
                        f"Zep batch {batch_id} item submission failed"
                    ) from e

            if len(item_details or []) != len(items):
                recovered_items = self._reconcile_batch_item_count(
                    batch_id,
                    expected_item_count,
                )
                recovered_indexes = {
                    getattr(item, "sequence_index", None)
                    for item in recovered_items
                }
                if (

View on GitHub (pinned to b5b53acc57)

Solutions

Retry the whole build resume flow: the persisted zep_batch_id/operation_id lets the API layer resume the existing batch instead of creating a new one.
Before retrying, inspect the batch in the Zep console: if items are partially present, either wait for listing consistency or delete the draft batch and restart cleanly.
Reduce batch_size (max 350) or chunk counts per submission to shrink the failure window.
Increase reconcile patience (retries/backoff in _reconcile_batch_item_count) if Zep's item listing lags.
Check the chained cause error to confirm it was genuinely retryable and not a misclassified auth error.

Example fix

# before
else:
    raise RuntimeError(
        f"Zep batch {batch_id} item submission is unconfirmed; the draft was not processed or replayed"
    ) from e

# after - retry reconciliation once after a short delay before refusing
else:
    time.sleep(2)
    recovered_items = self._reconcile_batch_item_count(batch_id, expected_item_count)
    recovered_indexes = {getattr(item, "sequence_index", None) for item in recovered_items}
    if len(recovered_items) == expected_item_count and recovered_indexes == set(range(expected_item_count)):
        item_details = recovered_items[i:expected_item_count]
    else:
        raise RuntimeError(
            f"Zep batch {batch_id} item submission is unconfirmed "
            f"(recovered {len(recovered_items)}/{expected_item_count}); "
            "the draft was not processed or replayed"
        ) from e

Defensive patterns

Strategy: retry

Try / catch

try:
    submission = builder.submit_document_batch(graph_id, chunks, batch_size=bs)
except RuntimeError as e:
    if 'item submission is unconfirmed' in str(e):
        # persisted zep_batch_id/operation_id allow the resume path to reconcile later
        logger.warning('Batch item add unconfirmed for %s; retry via resume', project.zep_batch_id)
        raise RetriableBuildError(str(e)) from e
    raise

Prevention

Persist batch identity immediately via batch_created_callback so any failure is resumable.
Keep batch_size modest to shrink the per-add failure window.
Verify Zep item listing is consistent (reconcile counts twice) before declaring unrecoverable.
Run builds with retry/backoff at the orchestration layer keyed on 'unconfirmed' errors.

When it happens

Trigger: A timeout/429/503 partway through batch.add for a chunk group; Zep accepted only some items before the connection broke; the reconcile listing itself is eventually consistent and shows fewer items than were actually accepted.

Common situations: Long builds (thousands of chunks) where a single flaky request out of hundreds triggers recovery; mobile/unstable server networking; Zep Cloud degraded performance making both add and list slow.

Related errors

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