{"record":{"id":"199ea196e3af11ad","repo":"iflytek/astron-agent","slug":"dataset-group-name-rest-response-missing-id-field","errorCode":null,"errorMessage":"Dataset '{group_name}' REST response missing id field","messagePattern":"Dataset '(.+?)' REST response missing id field","errorType":"exception","errorClass":"ValueError","httpStatus":null,"severity":"error","filePath":"core/knowledge/infra/ragflow/ragflow_client.py","lineNumber":543,"sourceCode":"        return sdk_datasets[0].upload_documents(\n            [{\"displayed_name\": filename, \"blob\": file_content}]\n        )\n\n    return await _upload_via_default_group(file_content=file_content, filename=filename)\n\n\nasync def _resolve_dataset_via_rest(group_name: str, rag: Any) -> Any:\n    \"\"\"Fallback: locate default-group dataset via REST when SDK name lookup fails.\n\n    Kept separate to avoid increasing default-group path complexity.\n    \"\"\"\n    rest_response = await list_datasets(name=group_name)\n    datasets = rest_response.get(\"data\", []) if rest_response else []\n    if not datasets:\n        raise ValueError(f\"Dataset '{group_name}' does not exist in RAGFlow\")\n    actual_id = datasets[0].get(\"id\")\n    if not actual_id:\n        raise ValueError(f\"Dataset '{group_name}' REST response missing id field\")\n    sdk_datasets: List[Any] = rag.list_datasets(id=actual_id)\n    if not sdk_datasets:\n        raise ValueError(\n            f\"Dataset '{group_name}' (id={actual_id}) not visible to ragflow_sdk\"\n        )\n    return sdk_datasets[0]\n\n\nasync def _upload_via_default_group(file_content: bytes, filename: str) -> List[Any]:\n    \"\"\"Legacy upload path using configured ``RAGFLOW_DEFAULT_GROUP``.\n\n    Kept separate to avoid increasing ``upload_document_to_dataset`` complexity.\n    \"\"\"\n    group_name = _config_value(\"default_group\", \"RAGFLOW_DEFAULT_GROUP\", \"\")\n    if not group_name:\n        raise ValueError(\n            \"RAGFLOW_DEFAULT_GROUP is not set; cannot upload without dataset_id\"\n        )","sourceCodeStart":525,"sourceCodeEnd":561,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/infra/ragflow/ragflow_client.py#L525-L561","documentation":"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.","triggerScenarios":"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.","commonSituations":"Upgrading or downgrading RAGFlow to a version with a different REST schema; pointing the client at a mock or third-party RAGFlow-compatible gateway.","solutions":["Check the RAGFlow server version and confirm GET /api/v1/datasets returns objects with an 'id' field (curl and inspect JSON).","Upgrade the client/server pairing to compatible versions where the dataset schema includes 'id'.","Inspect any proxy/gateway between the service and RAGFlow for response rewriting.","Add logging of the raw REST response to capture the actual payload shape for diagnosis."],"exampleFix":"# before: trusting response blindly\nactual_id = datasets[0].get(\"id\")\n# after: fail fast with a clear payload dump\ndatasets = rest_response.get(\"data\", []) if rest_response else []\nif not datasets or not datasets[0].get(\"id\"):\n    raise ValueError(f\"Unexpected RAGFlow list_datasets payload: {rest_response!r}\")","handlingStrategy":"type-guard","validationCode":"def response_has_ids(rest_response: dict | None) -> bool:\n    data = (rest_response or {}).get(\"data\") or []\n    return bool(data) and all(isinstance(d.get(\"id\"), str) and d[\"id\"] for d in data)","typeGuard":"def has_valid_id(dataset: dict) -> bool:\n    return isinstance(dataset, dict) and isinstance(dataset.get(\"id\"), str) and bool(dataset[\"id\"])","tryCatchPattern":"try:\n    doc = await upload_document_to_dataset(content, filename)\nexcept ValueError as e:\n    if \"REST response missing id\" in str(e):\n        logger.error(f\"RAGFlow response schema mismatch: {e}\")\n    raise","preventionTips":["Pin and test the client against the deployed RAGFlow server version","Add a contract test asserting list_datasets items contain 'id'","Log raw REST payloads on schema mismatch"],"tags":["ragflow","api-contract","unexpected-response-shape"],"backgroundTag":"unexpected-api-response-shape","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-19T12:17:13.211Z"}