iflytek/astron-agent · error · ValueError

ragflow_ext is only allowed when ragType='Ragflow-RAG', got…

Error message

ragflow_ext is only allowed when ragType='Ragflow-RAG', got ragType='{self.ragType.value}'

What it means

ChunkQueryReq is a Pydantic model with an @model_validator(mode="after") that rejects requests combining ragflow_ext (RAGFlow-specific retrieval parameters like top_k) with any ragType other than RAGType.RagFlow_RAG. The validator runs automatically after field validation whenever the model is constructed, so any code path that builds a ChunkQueryReq with a mismatched pair fails at instantiation with a ValueError surfaced by Pydantic as a ValidationError.

Solutions

1. Set ragType to RAGType.RagFlow_RAG if RAGFlow-specific retrieval is genuinely required.
2. Otherwise omit ragflow_ext (or set it to None) from the ChunkQueryReq payload.
3. In the caller, conditionally include ragflow_ext only when the backend is RagFlow, e.g. build kwargs based on the active RAG type.
4. In API client code, validate/strip ragflow_ext before sending when ragType is not Ragflow-RAG.

Example fix

// before
req = ChunkQueryReq(query="q", topN=3, match=m, ragType=RAGType.SPARKDESK_RAG, ragflow_ext=RagflowQueryExt(top_k=3))
// after
req = ChunkQueryReq(query="q", topN=3, match=m, ragType=RAGType.RagFlow_RAG, ragflow_ext=RagflowQueryExt(top_k=3))
# or drop the ext:
req = ChunkQueryReq(query="q", topN=3, match=m, ragType=RAGType.SPARKDESK_RAG)

def can_use_ragflow_ext(rag_type: RAGType, ragflow_ext) -> bool:
    return ragflow_ext is None or rag_type == RAGType.RagFlow_RAG
# call before constructing ChunkQueryReq

def is_ragflow(rag_type: RAGType) -> bool:
    return rag_type == RAGType.RagFlow_RAG

try:
    req = ChunkQueryReq(**payload)
except ValidationError as e:
    logger.warning("Invalid chunk query request: %s", e)
    raise HTTPException(status_code=422, detail=str(e))

When it happens

Trigger: Constructing ChunkQueryReq (directly or via an API payload) with ragflow_ext set to a non-None RagflowQueryExt while ragType is anything other than RAGType.RagFlow_RAG (e.g. SPARKDESK-RAG or AIUI-RAG).

Common situations: Clients reusing a request template built for RAGFlow against another RAG backend; a caller hardcoding ragflow_ext.top_k from older code; frontend sending extra RAGFlow fields unconditionally; configuration where ragType was changed but the extension block was left in place.

Understand the failure class

Background: Schema validation failed / invalid input schema: payload rejected because its shape doesn't match the expected schema — this error's family across 28 libraries.

Related errors

• REPO_TYPE_NOT_MATCH
• group is required when ragType is not Ragflow-RAG
• fileUrl is required
• docIds is not empty
• Invalid group: . Valid options

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

Appendix: source

Thrown at core/knowledge/domain/entity/chunk_dto.py:296

            "send the raw query (useful for keyword / highlight matching)."
        ),
    )
    match: QueryMatch = Field(..., description="Matching conditions")
    ragType: RAGType = Field(..., description="RAG type")
    history: List[Dict[str, Any]] = Field(default_factory=list)
    ragflow_ext: Optional[RagflowQueryExt] = Field(
        default=None,
        description=(
            "Optional RAGFlow-specific retrieval parameters. Requires "
            "ragType=Ragflow-RAG; other RAG types return a validation "
            "error. When ragflow_ext.top_k is set, it overrides topN."
        ),
    )

    @model_validator(mode="after")
    def _ragflow_ext_scope_check(self) -> "ChunkQueryReq":
        if self.ragflow_ext is not None and self.ragType != RAGType.RagFlow_RAG:
            raise ValueError(
                f"ragflow_ext is only allowed when ragType='Ragflow-RAG', "
                f"got ragType='{self.ragType.value}'"
            )
        return self


class QueryDocReq(BaseModel):
    """
    Document query request model

    Attributes:
        docId: Document ID, required
        ragType: RAG type
        group: Knowledge base group used by non-Ragflow strategies, optional
        datasetId: RAGFlow dataset.id for direct routing, optional
    """

    docId: str = Field(..., min_length=1, description="Required, minimum length 1")

View on GitHub (pinned to 5e758547a8)