666ghj/MiroFish · error · ValueError

Zep batch item exceeds 10,000 characters at chunk {oversized

Error message

Zep batch item exceeds 10,000 characters at chunk {oversized[0]}

What it means

Raised by GraphBuilder.validate_batch_chunks, a pre-flight check that runs before any Zep Cloud mutation. Zep's Batch API rejects individual text items longer than 10,000 characters, so this guard fails fast with the index of the first offending chunk instead of letting the whole batch fail server-side after submission. It is a ValueError raised entirely client-side, so hitting it means no API quota was consumed and no partial state was created in Zep.

Source

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

            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}",
            )
            items.extend(getattr(page, "items", None) or [])
            next_cursor = getattr(page, "next_cursor", None)

View on GitHub (pinned to b5b53acc57)

Solutions

1. Reduce the chunker's max chunk size so no chunk exceeds 10,000 characters (e.g. chunk_size=2000 with an overlap), then rebuild.
2. Inspect the offending chunk (the message reports its index) to find why it was not split — often a single line/paragraph with no separator; enable hard character-based splitting as a fallback.
3. If the text is legitimately monolithic (one giant string with no separators), force character-window splitting at the API boundary before validate_batch_chunks.

Example fix

// before
chunks = [document_text]  # single 80k-char document
GraphBuilder.validate_batch_chunks(chunks)
# after
chunk_size = 4000
chunks = [document_text[i:i + chunk_size]
          for i in range(0, len(document_text), chunk_size)]
GraphBuilder.validate_batch_chunks(chunks)

def chunks_within_limit(chunks: list[str], limit: int = 10_000) -> bool:
    return all(len(c) <= limit for c in chunks)

# before ingestion:
assert chunks_within_limit(chunks), 'split chunks to <=10000 chars'

When it happens

Trigger: Calling the batch-ingestion path (validate_batch_chunks) with a chunk list where at least one element exceeds 10,000 characters. Typically caused by a chunker that did not split a long document (e.g., a single huge section, min-chunk-size set above 10k, or a document with no natural split points such as one giant paragraph or table dump).

Common situations: Loading an unusually long flat file (logs, CSV, concatenated JSON), changing chunk_size/chunk_overlap configuration upward, feeding non-chunked text for testing, or a chunker bug that yields the whole document as one chunk. Also appears after switching embedding strategies that assume larger contexts.

Related errors

• Zep batch {submission.batch_id} returned an incomplete item
• graph_id is required
• At least one text chunk is required
• batch_size must be between 1 and 350
• A Zep batch cannot contain more than 50,000 items

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