iflytek/astron-agent · error · CustomException

ChunkQueryFailed

ChunkQueryFailed

Error message

RAGFlow produced zero chunks for document {doc_id}

What it means

Raised by _validate_document_chunks (core/knowledge/service/impl/ragflow_strategy.py:337) when RAGFlow finished parsing a document but returned zero chunks. Split/upsert treat an empty chunk set as a failed ingestion (CustomException with ChunkQueryFailed) and roll back the newly uploaded document, because empty output usually means parsing produced nothing usable.

Solutions

1. Check the document's run status in RAGFlow — if FAIL, read the parse error and fix the file or parser config before retrying.
2. Verify the source file actually contains extractable text (open it or run pdftotext); use an OCR-capable parser for scanned documents.
3. Try parsing with default parser_config to rule out a separator/chunk_token_num setting that filters out all content.
4. Increase wait_for_parsing timeout (currently 300s) for very large documents that may still be parsing when chunks are fetched.
5. If the file legitimately has no text, reject it upstream instead of uploading to RAGFlow.

Example fix

// before: uploading image-only PDF with naive parser
chunks = await strategy.split(fileUrl=scan_pdf_url)

// after: reject empty/unextractable inputs and verify parse status
if not extractable_text(file_content):
    raise ValueError("File contains no extractable text; OCR required")
chunks = await strategy.split(fileUrl=scan_pdf_url)
// on ChunkQueryFailed, inspect doc run status:
doc = await ragflow_client.get_document_info(dataset_id, doc_id)
logger.info("run status: %s", doc.get("run"))

# before uploading, ensure the source has extractable text
text = extract_text_preview(file_content)  # e.g. pdftotext / docx read
if not text.strip():
    raise ValueError("file contains no extractable text (OCR needed?)")

def chunks_nonempty(chunks_data) -> bool:
    return isinstance(chunks_data, list) and len(chunks_data) > 0

try:
    chunks = await strategy.split(fileUrl=url)
except CustomException as e:
    if e.code == CodeEnum.ChunkQueryFailed:
        doc = await ragflow_client.get_document_info(dataset_id, e.doc_id)
        logger.error("parse ended run=%s with zero chunks", doc and doc.get("run"))
    raise

When it happens

Trigger: Calling split() (fresh upload path or _upsert_document) where get_document_chunks returns [] after wait_for_parsing reports completion — e.g. the document contains no extractable text (image-only PDF, empty file), the parser failed silently, or wait_for_parsing timed out and reported an interim status as final.

Common situations: Uploading scanned/image PDFs without OCR enabled in the RAGFlow parser config; uploading a file whose format RAGFlow's parser cannot extract (encrypted PDF, exotic format); RAGFlow parse 'completed' with RUN status FAIL or a zero-chunk DONE due to version quirks; chunk_token_num/separator config excludes all content.

Understand the failure class

Background: EmptyResultError / "no results found": when an API or scraper succeeds but returns zero rows — this error's family across 9 libraries.

Related errors

• REPO_KNOWLEDGE_GET_FAILED
• File chunking processing failed
• -40008
• REPO_CREATE_RAGFLOW_FAILED
• Unable to parse boolean value: '

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

Appendix: source

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

            doc_id,
            final_status,
        )

    def _validate_document_chunks(
        self,
        doc_id: str,
        chunks_data: List[Dict[str, Any]],
    ) -> None:
        """Reject empty RAGFlow output.

        A large single chunk is valid when the source contains no configured
        delimiter: RAGFlow v0.20.5's naive merger does not forcibly split one
        oversized segment. Console therefore stores such chunks in LONGTEXT
        instead of treating their size as proof that configuration was ignored.
        """
        if not chunks_data:
            logger.error("RAGFlow produced zero chunks: doc=%s", doc_id)
            raise CustomException(
                CodeEnum.ChunkQueryFailed,
                f"RAGFlow produced zero chunks for document {doc_id}",
            )

    async def split(
        self,
        fileUrl: Optional[str] = None,
        lengthRange: Optional[List[int]] = None,
        overlap: int = 16,
        resourceType: int = 0,
        separator: Optional[List[str]] = None,
        titleSplit: bool = False,
        cutOff: Optional[List[str]] = None,
        document_id: Optional[str] = None,
        **kwargs: Any,
    ) -> List[Dict[str, Any]]:
        """
        Split file into chunks using RAGFlow.

View on GitHub (pinned to 5e758547a8)