iflytek/astron-agent · error · ValueError

Dataset id= not visible to RAGFlow SDK; refusing to…

Error message

Dataset id={dataset_id} not visible to RAGFlow SDK; refusing to silently fall back to RAGFLOW_DEFAULT_GROUP to avoid cross-repo upload contamination

What it means

upload_document_to_dataset resolves the target dataset through the official RAGFlow SDK (rag.list_datasets(id=...)). If the SDK cannot see the given dataset_id, the function refuses to proceed: it raises ValueError explicitly rather than silently falling back to the RAGFLOW_DEFAULT_GROUP dataset, preventing documents from being uploaded into the wrong (default/shared) dataset — cross-repo contamination.

Solutions

Verify the dataset_id exists and is visible to the configured RAGFLOW_API_TOKEN via list_datasets (UI or REST call)
Re-create the dataset if it was deleted and use the new id
Check that RAGFLOW_BASE_URL/RAGFLOW_API_TOKEN point to the same RAGFlow instance the dataset belongs to
If intentional, upload without dataset_id so the documented fallback/default-group path applies explicitly

Example fix

# before
await upload_document_to_dataset(stale_dataset_id, filename, blob)  # raises
# after
datasets = await list_datasets()
target = next((d for d in datasets if d['name'] == dataset_name), None)
if target is None:
    target = await create_dataset(dataset_name)
await upload_document_to_dataset(target['id'], filename, blob)

Defensive patterns

Strategy: validation

Validate before calling

async def dataset_visible(dataset_id: str) -> bool:
    rag = get_rag_object()
    return bool(rag.list_datasets(id=dataset_id))

Try / catch

try:
    await upload_document_to_dataset(dataset_id, filename, blob)
except ValueError as e:
    if 'not visible to RAGFlow SDK' in str(e):
        logger.error('Dataset %s unknown to RAGFlow; resolve id before upload', dataset_id)
        raise

Prevention

Resolve dataset ids from list_datasets on the same RAGFlow instance/token at upload time
Never cache dataset ids across environments (dev/prod)
Keep RAGFLOW_BASE_URL and RAGFLOW_API_TOKEN pointing at one instance per deployment
Prefer creating the dataset programmatically when the id cannot be verified

When it happens

Trigger: Calling upload_document_to_dataset with a dataset_id that does not exist in RAGFlow, belongs to another tenant/API key, or was created outside the SDK's visibility, so rag.list_datasets(id=dataset_id) returns an empty list.

Common situations: Stale dataset id cached after the dataset was deleted; using a dataset created under a different RAGFlow API token; id copied from a different RAGFlow instance/environment (dev vs prod); tenant/space mismatch where the console passes an internal id that RAGFlow does not know.

Understand the failure class

Background: "Not found" and "does not exist" errors: why "Task not found", "No such folder", and "Can't find" fire when a lookup comes back empty — this error's family across 14 libraries.

Related errors

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

Appendix: source

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

      before any dataset lookup.

    Args:
        dataset_id: Dataset ID; empty string triggers configured fallback.
        file_content: File content bytes.
        filename: File name.

    Returns:
        Upload response containing document ID(s).

    Raises:
        ValueError: If ``dataset_id`` is provided but not resolvable via SDK,
            or if the configured fallback cannot resolve a dataset.
    """
    if dataset_id:
        rag = get_rag_object()
        sdk_datasets: List[Any] = rag.list_datasets(id=dataset_id)
        if not sdk_datasets:
            raise ValueError(
                f"Dataset id={dataset_id} not visible to RAGFlow SDK; "
                "refusing to silently fall back to RAGFLOW_DEFAULT_GROUP "
                "to avoid cross-repo upload contamination"
            )
        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 []

View on GitHub (pinned to 5e758547a8)