iflytek/astron-agent · error · CustomException

ParameterInvalid

ParameterInvalid

Error message

Chunk {i} content cannot be empty

What it means

A chunk in the submitted list has no usable content: chunk.get("content", "") is empty/None. Content is mandatory for a RAGFlow chunk, so _process_single_chunk raises ParameterInvalid instead of calling the API.

Solutions

1. Filter out chunks with empty/whitespace-only content before calling chunks_save.
2. Fix the producer so every chunk dict includes a non-empty "content" key.
3. If the upstream parser creates empty segments, drop or merge them at split time.
4. Map the source field name correctly (e.g. text -> content) when building the request.

Example fix

// before
chunks = [{"dataIndex": 0}, {"content": "", "dataIndex": 1}]
await strategy.chunks_save(docId=doc_id, chunks=chunks, dataset_id=ds)
// after
clean = [c for c in chunks if (c.get("content") or "").strip()]
await strategy.chunks_save(docId=doc_id, chunks=clean, dataset_id=ds)

def valid_chunks(chunks):
    return isinstance(chunks, list) and all(
        isinstance(c, dict) and isinstance(c.get("content"), str) and c["content"].strip()
        for c in chunks
    )

def is_contentful_chunk(c) -> bool:
    return isinstance(c, dict) and bool(isinstance(c.get("content"), str) and c["content"].strip())

try:
    await strategy.chunks_save(docId=doc_id, chunks=chunks, dataset_id=ds)
except CustomException as e:
    if "content cannot be empty" in str(e):
        logger.warning("dropping empty chunk batch for %s", doc_id)
    else:
        raise

When it happens

Trigger: chunks_save called with a chunk dict missing the "content" key, content set to "" or null; upstream splitter produced empty segments (e.g. blank pages, whitespace-only blocks).

Common situations: Frontend sends chunks where the text field is named differently (text vs content); document parser yields empty chunks for image-only pages; batch built programmatically with placeholder empty dicts.

Understand the failure class

Background: "must not be empty", "cannot be empty" — required-field validation errors across open-source libraries — this error's family across 41 libraries.

Related errors

• PARAMETER_ERROR
• fileUrl is required
• docIds is not empty
• file is required
• chunkIds is not empty

AI-assisted analysis of iflytek/astron-agent@5e758547a8 (2026-09-12). Data as JSON: /api/errors/33d669f78f1d77bc. Report an issue: GitHub.

Appendix: source

Thrown at core/knowledge/service/impl/ragflow_strategy.py:590

            f"established {len(existing_chunks)} mappings"
        )
        return existing_chunks

    async def _process_single_chunk(
        self,
        i: int,
        chunk: Dict,
        dataset_id: str,
        doc_id: str,
        existing_chunks: Dict,
        current_time: str,
    ) -> Dict[str, Any]:
        """Process saving of single chunk"""
        try:
            content = chunk.get("content", "")
            if not content:
                logger.warning(f"Chunk {i} content is empty, skipping")
                raise CustomException(
                    CodeEnum.ParameterInvalid, f"Chunk {i} content cannot be empty"
                )

            data_index = str(chunk.get("dataIndex", i))

            # Check if chunk already exists
            if data_index in existing_chunks:
                existing_chunk = existing_chunks[data_index]
                logger.info(
                    f"Chunk dataIndex={data_index} already exists, returning directly: {existing_chunk.get('id')}"
                )

                return {
                    "id": existing_chunk.get("id"),
                    "datasetId": dataset_id,
                    "fileId": doc_id,
                    "createTime": existing_chunk.get("create_time", current_time),
                    "updateTime": existing_chunk.get("update_time", current_time),

View on GitHub (pinned to 5e758547a8)