{"record":{"id":"33d669f78f1d77bc","repo":"iflytek/astron-agent","slug":"parameterinvalid-chunk-i-content-cannot-be-empty","errorCode":"ParameterInvalid","errorMessage":"Chunk {i} content cannot be empty","messagePattern":"Chunk (.+?) content cannot be empty","errorType":"error_code","errorClass":"CustomException","httpStatus":null,"severity":"error","filePath":"core/knowledge/service/impl/ragflow_strategy.py","lineNumber":590,"sourceCode":"            f\"established {len(existing_chunks)} mappings\"\n        )\n        return existing_chunks\n\n    async def _process_single_chunk(\n        self,\n        i: int,\n        chunk: Dict,\n        dataset_id: str,\n        doc_id: str,\n        existing_chunks: Dict,\n        current_time: str,\n    ) -> Dict[str, Any]:\n        \"\"\"Process saving of single chunk\"\"\"\n        try:\n            content = chunk.get(\"content\", \"\")\n            if not content:\n                logger.warning(f\"Chunk {i} content is empty, skipping\")\n                raise CustomException(\n                    CodeEnum.ParameterInvalid, f\"Chunk {i} content cannot be empty\"\n                )\n\n            data_index = str(chunk.get(\"dataIndex\", i))\n\n            # Check if chunk already exists\n            if data_index in existing_chunks:\n                existing_chunk = existing_chunks[data_index]\n                logger.info(\n                    f\"Chunk dataIndex={data_index} already exists, returning directly: {existing_chunk.get('id')}\"\n                )\n\n                return {\n                    \"id\": existing_chunk.get(\"id\"),\n                    \"datasetId\": dataset_id,\n                    \"fileId\": doc_id,\n                    \"createTime\": existing_chunk.get(\"create_time\", current_time),\n                    \"updateTime\": existing_chunk.get(\"update_time\", current_time),","sourceCodeStart":572,"sourceCodeEnd":608,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/service/impl/ragflow_strategy.py#L572-L608","documentation":"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.","triggerScenarios":"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).","commonSituations":"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.","solutions":["Filter out chunks with empty/whitespace-only content before calling chunks_save.","Fix the producer so every chunk dict includes a non-empty \"content\" key.","If the upstream parser creates empty segments, drop or merge them at split time.","Map the source field name correctly (e.g. text -> content) when building the request."],"exampleFix":"// before\nchunks = [{\"dataIndex\": 0}, {\"content\": \"\", \"dataIndex\": 1}]\nawait strategy.chunks_save(docId=doc_id, chunks=chunks, dataset_id=ds)\n// after\nclean = [c for c in chunks if (c.get(\"content\") or \"\").strip()]\nawait strategy.chunks_save(docId=doc_id, chunks=clean, dataset_id=ds)","handlingStrategy":"validation","validationCode":"def valid_chunks(chunks):\n    return isinstance(chunks, list) and all(\n        isinstance(c, dict) and isinstance(c.get(\"content\"), str) and c[\"content\"].strip()\n        for c in chunks\n    )","typeGuard":"def is_contentful_chunk(c) -> bool:\n    return isinstance(c, dict) and bool(isinstance(c.get(\"content\"), str) and c[\"content\"].strip())","tryCatchPattern":"try:\n    await strategy.chunks_save(docId=doc_id, chunks=chunks, dataset_id=ds)\nexcept CustomException as e:\n    if \"content cannot be empty\" in str(e):\n        logger.warning(\"dropping empty chunk batch for %s\", doc_id)\n    else:\n        raise","preventionTips":["Filter whitespace-only chunks at the splitter output.","Normalize field names (text -> content) at the API boundary.","Unit-test splitters against blank/image-only documents."],"tags":["validation","chunks","parameter","empty-content"],"backgroundTag":"empty-required-field","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}