iflytek/astron-agent · error · ValueError

When repoType=2, match.docIds is required and must contain…

Error message

When repoType=2, match.docIds is required and must contain at least one item.

What it means

Pydantic model_validator on the Knowledge model of an agent node: when repoType is 2 (selected-documents mode), match.docIds must be a non-empty list. The model enforces this at parse/validation time, raising ValueError which Pydantic surfaces as a validation error before the node executes.

Solutions

1. Populate match.docIds with at least one document ID when repoType=2
2. Change repoType to 1 (or another mode) if whole-repository retrieval is intended and no specific docs are needed
3. Add an upstream check in the workflow builder/UI to require doc selection before saving repoType=2

Example fix

// before
{"repoType": 2, "match": {"docIds": []}}
// after
{"repoType": 2, "match": {"docIds": ["doc-123"]}}

def knowledge_config_valid(k: dict) -> bool:
    if k.get("repoType") == 2:
        ids = (k.get("match") or {}).get("docIds") or []
        return len(ids) > 0
    return True

from pydantic import ValidationError
try:
    knowledge = Knowledge.model_validate(cfg)
except ValidationError as e:
    notify_user("doc selection required when repoType=2")
    return

When it happens

Trigger: Defining a Knowledge config in an agent node with repoType=2 but omitting match.docIds, sending an empty list [], or docIds being null — typically from a programmatically built or hand-edited workflow definition.

Common situations: Building agent node configs from code where doc selection state was not persisted; copying a knowledge config from repoType=1 (whole repo) and flipping repoType to 2 without adding docIds; UI saving an empty selection.

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

• skillId is required
• audio_data cannot be empty
• CODE_EXEC_MEMORY_LIMIT_MB must be between
• CODE_EXEC_TIMEOUT_SEC must be between
• group is required when ragType is not Ragflow-RAG

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

Appendix: source

Thrown at core/workflow/engine/nodes/agent/agent_node.py:111

    :param name: Knowledge base name
    :param description: Knowledge base description
    :param topK: Number of top results to retrieve
    :param repoType: Repository type (default: CBG_RAG)
    :param match: Matching configuration for repositories and documents
    """

    name: str = Field(min_length=1, max_length=128)
    description: str = Field(min_length=0, max_length=1024)
    topK: int = Field(ge=1, le=5)
    repoType: int = Field(..., ge=1, le=3)
    match: Match

    @model_validator(mode="after")
    def check_doc_ids_when_repo_type(self) -> "Knowledge":
        if self.repoType == 2:
            if self.match.docIds is None or len(self.match.docIds) == 0:
                raise ValueError(
                    "When repoType=2, match.docIds is required and must contain at least one item."
                )
        return self


class Skill(BaseModel):
    """Skill metadata passed to agent runtime.

    :param skillId: Skill file identifier
    :param name: Skill display name
    :param description: Short summary injected into system prompt
    :param downloadUrl: Presigned URL for lazily reading full SKILL.md content
    :param resources: Relative-path resource manifest for referenced files
    """

    class Resource(BaseModel):
        path: str = Field(min_length=1)
        name: str = Field(default="")

View on GitHub (pinned to 5e758547a8)