666ghj/MiroFish · warning · ValueError

A Zep batch cannot contain more than 50,000 items

Error message

A Zep batch cannot contain more than 50,000 items

What it means

ValueError from validate_batch_chunks: more than 50,000 chunks were produced for a single Zep batch, exceeding the Batch API's total item ceiling. Like the other checks it runs before the first Cloud mutation, so nothing is created; the caller must split the work across multiple batches or reduce chunk count.

Source

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

                ) from error

        return BatchSubmission(
            batch_id=batch_id,
            operation_id=operation_id,
            episode_uuids=episode_uuids,
            item_count=total_chunks,
        )

    @staticmethod
    def validate_batch_chunks(chunks: List[str], *, batch_size: int = 350) -> None:
        """Validate every Batch API limit before the first Cloud mutation."""

        if not chunks:
            raise ValueError("At least one text chunk is required")
        if not 1 <= batch_size <= 350:
            raise ValueError("batch_size must be between 1 and 350")
        if len(chunks) > 50_000:
            raise ValueError("A Zep batch cannot contain more than 50,000 items")
        oversized = [index for index, chunk in enumerate(chunks) if len(chunk) > 10_000]
        if oversized:
            raise ValueError(
                f"Zep batch item exceeds 10,000 characters at chunk {oversized[0]}"
            )

    def _list_batch_items(self, batch_id: str) -> List[Any]:
        items: List[Any] = []
        cursor: int | None = None
        seen_cursors: set[int] = set()
        while True:
            page = call_zep_read_with_retry(
                lambda: self.client.batch.list_items(
                    batch_id=batch_id,
                    limit=100,
                    cursor=cursor,
                ),
                operation_name=f"list batch items {batch_id}",

View on GitHub (pinned to b5b53acc57)

Solutions

1. Increase chunk_size (and adjust overlap) so total chunks fall under 50,000 for the same text.
2. Or split the document into multiple build operations, each under the cap, and merge at the graph level.
3. Add a pre-flight estimate at the API layer: expected_chunks ≈ ceil(len(text) / (chunk_size - overlap)) and reject early with guidance.
4. Log text length and chunk parameters whenever this fires to spot misconfiguration patterns.

Example fix

# before
chunks = TextProcessor.split_text(text, chunk_size=chunk_size, overlap=chunk_overlap)
builder.validate_batch_chunks(chunks, batch_size=batch_size)

# after - pre-flight estimate with an actionable message, then shard if still over
estimated = -(-len(text) // max(1, chunk_size - chunk_overlap))
if estimated > 50_000:
    raise ValueError(
        f"Document would produce ~{estimated} chunks; Zep allows 50,000 per batch. "
        "Increase chunk_size or split the document into multiple builds."
    )
chunks = TextProcessor.split_text(text, chunk_size=chunk_size, overlap=chunk_overlap)
builder.validate_batch_chunks(chunks, batch_size=batch_size)

estimated = -(-len(text) // max(1, chunk_size - chunk_overlap))
if estimated > 50_000:
    raise ValueError(f'Document would produce ~{estimated} chunks; Zep caps batches at 50,000 items. Increase chunk_size or split the build.')
chunks = TextProcessor.split_text(text, chunk_size=chunk_size, overlap=chunk_overlap)
builder.validate_batch_chunks(chunks, batch_size=batch_size)

try:
    builder.validate_batch_chunks(chunks, batch_size=batch_size)
except ValueError as e:
    if '50,000' in str(e):
        chunk_size = max(chunk_size, math.ceil(len(text) / 49_000))  # enlarge chunks to fit, then re-split
        chunks = TextProcessor.split_text(text, chunk_size=chunk_size, overlap=chunk_overlap)
        builder.validate_batch_chunks(chunks, batch_size=batch_size)
    else:
        raise

When it happens

Trigger: Very large documents combined with small chunk_size (e.g. 50M chars at chunk_size 1000 → 50k+ chunks); chunk_size/chunk_overlap misconfigured (tiny chunks) exploding the count; concatenating multiple documents into one build call.

Common situations: Users uploading book-scale corpora in one project; a UI or config change lowering chunk_size without accounting for the item cap; automated pipelines feeding ever-growing transcripts into a single build.

Related errors

• graph_id is required
• At least one text chunk is required
• batch_size must be between 1 and 350
• Graph {graph_id} is in use by active consumer(s): {', '.join
• Persisted Zep batch does not match the current graph input

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