iflytek/astron-agent · error · ValueError

Dataset ' ' REST response missing id field

Error message

Dataset '{group_name}' REST response missing id field

What it means

Raised when the REST list_datasets response for the group name matched a dataset but its first entry lacks the 'id' field. This indicates a malformed or unexpected API response rather than a missing dataset.

Solutions

1. Check the RAGFlow server version and confirm GET /api/v1/datasets returns objects with an 'id' field (curl and inspect JSON).
2. Upgrade the client/server pairing to compatible versions where the dataset schema includes 'id'.
3. Inspect any proxy/gateway between the service and RAGFlow for response rewriting.
4. Add logging of the raw REST response to capture the actual payload shape for diagnosis.

Example fix

# before: trusting response blindly
actual_id = datasets[0].get("id")
# after: fail fast with a clear payload dump
datasets = rest_response.get("data", []) if rest_response else []
if not datasets or not datasets[0].get("id"):
    raise ValueError(f"Unexpected RAGFlow list_datasets payload: {rest_response!r}")

def response_has_ids(rest_response: dict | None) -> bool:
    data = (rest_response or {}).get("data") or []
    return bool(data) and all(isinstance(d.get("id"), str) and d["id"] for d in data)

def has_valid_id(dataset: dict) -> bool:
    return isinstance(dataset, dict) and isinstance(dataset.get("id"), str) and bool(dataset["id"])

try:
    doc = await upload_document_to_dataset(content, filename)
except ValueError as e:
    if "REST response missing id" in str(e):
        logger.error(f"RAGFlow response schema mismatch: {e}")
    raise

When it happens

Trigger: RAGFlow server version returning a changed/legacy response envelope where items have no 'id' key; a proxy or gateway rewriting the JSON body; non-standard RAGFlow-compatible server implementations.

Common situations: Upgrading or downgrading RAGFlow to a version with a different REST schema; pointing the client at a mock or third-party RAGFlow-compatible gateway.

Understand the failure class

Background: "invalid response format", "malformed payload", "missing data field": when an API returns 200 but the response shape is wrong — this error's family across 23 libraries.

Related errors

• All retry attempts failed
• API request failed
• Cannot provide both fileUrl and file parameters
• ChunkDeleteFailed
• ChunkQueryFailed

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

Appendix: source

Thrown at core/knowledge/infra/ragflow/ragflow_client.py:543

        return sdk_datasets[0].upload_documents(
            [{"displayed_name": filename, "blob": file_content}]
        )

    return await _upload_via_default_group(file_content=file_content, filename=filename)


async def _resolve_dataset_via_rest(group_name: str, rag: Any) -> Any:
    """Fallback: locate default-group dataset via REST when SDK name lookup fails.

    Kept separate to avoid increasing default-group path complexity.
    """
    rest_response = await list_datasets(name=group_name)
    datasets = rest_response.get("data", []) if rest_response else []
    if not datasets:
        raise ValueError(f"Dataset '{group_name}' does not exist in RAGFlow")
    actual_id = datasets[0].get("id")
    if not actual_id:
        raise ValueError(f"Dataset '{group_name}' REST response missing id field")
    sdk_datasets: List[Any] = rag.list_datasets(id=actual_id)
    if not sdk_datasets:
        raise ValueError(
            f"Dataset '{group_name}' (id={actual_id}) not visible to ragflow_sdk"
        )
    return sdk_datasets[0]


async def _upload_via_default_group(file_content: bytes, filename: str) -> List[Any]:
    """Legacy upload path using configured ``RAGFLOW_DEFAULT_GROUP``.

    Kept separate to avoid increasing ``upload_document_to_dataset`` complexity.
    """
    group_name = _config_value("default_group", "RAGFLOW_DEFAULT_GROUP", "")
    if not group_name:
        raise ValueError(
            "RAGFLOW_DEFAULT_GROUP is not set; cannot upload without dataset_id"
        )

View on GitHub (pinned to 5e758547a8)