666ghj/MiroFish · warning · ValueError

At least one text chunk is required

Error message

At least one text chunk is required

What it means

ValueError from the static validate_batch_chunks (graph_builder.py): the chunks list passed to a Zep batch submission is empty. Zep's Batch API requires at least one item, and the validation runs before the first Cloud mutation (per its docstring), so no graph or batch is touched when it fires.

Source

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

            )
            if getattr(summary, "status", None) in {None, "draft"}:
                raise RuntimeError(
                    f"Zep batch {batch_id} processing is unconfirmed"
                ) 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,

View on GitHub (pinned to b5b53acc57)

Solutions

1. Check the source text passed to TextProcessor.split_text — it is empty or normalizes to nothing.
2. Reject empty documents at the API layer (request validation) before invoking the builder.
3. If preprocessing removes all content, loosen the filter or surface a clearer 'document has no extractable text' error.
4. Log the raw document length/first bytes at intake to catch silent upload failures.

Example fix

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

# after - validate the source text first with a user-facing message
if not text or not text.strip():
    raise ValueError("Document text is empty; nothing to build a graph from")
chunks = TextProcessor.split_text(text, chunk_size=chunk_size, overlap=chunk_overlap)
builder.validate_batch_chunks(chunks, batch_size=350)

if not text or not text.strip():
    raise ValueError('Document text is empty; nothing to build a graph from')
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 'At least one text chunk' in str(e):
        return HTTPException(status_code=422, detail='Uploaded document contains no extractable text')
    raise

When it happens

Trigger: TextProcessor.split_text returned zero chunks because the input text was empty/whitespace; upstream filtering stripped all chunks; a caller passed an uninitialized list; resume path re-splitting edited-down-to-empty text.

Common situations: User submits an empty document or one containing only whitespace/punctuation removed by preprocessing; file upload silently failed and produced an empty string; OCR extraction returned nothing.

Related errors

• graph_id is required
• batch_size must be between 1 and 350
• A Zep batch cannot contain more than 50,000 items
• 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/ed79493ac32a4f0f. Report an issue: GitHub.