iflytek/astron-agent · error · ValueError

RAGFLOW_DEFAULT_GROUP is not set; cannot upload without…

Error message

RAGFLOW_DEFAULT_GROUP is not set; cannot upload without dataset_id

What it means

Legacy upload path (_upload_via_default_group) raises this when neither an explicit dataset_id was supplied nor RAGFLOW_DEFAULT_GROUP is configured. Without one of these the client has no target dataset to upload into.

Solutions

Set RAGFLOW_DEFAULT_GROUP to the name of an existing RAGFlow dataset in the service environment.
Pass an explicit dataset_id to upload_document_to_dataset instead of relying on the default group.
Confirm the env var reaches the container (docker compose config / kubectl describe pod env).
Verify _config_value reads the correct config source and that .env files are loaded.

Example fix

# before
# RAGFLOW_DEFAULT_GROUP unset
# after (docker-compose.yml)
knowledge:
  environment:
    RAGFLOW_DEFAULT_GROUP: knowledge-base

Defensive patterns

Strategy: validation

Validate before calling

group = os.getenv("RAGFLOW_DEFAULT_GROUP", "")
if not group.strip():
    raise RuntimeError("Set RAGFLOW_DEFAULT_GROUP or pass dataset_id explicitly")

Try / catch

try:
    doc = await upload_document_to_dataset(content, filename)
except ValueError as e:
    if "RAGFLOW_DEFAULT_GROUP is not set" in str(e):
        logger.error("Missing upload target: set RAGFLOW_DEFAULT_GROUP or pass dataset_id")
    raise

Prevention

Declare RAGFLOW_DEFAULT_GROUP in .env.example and compose/k8s manifests
Fail fast at service startup if required RAGFlow config is absent
Prefer passing explicit dataset_id over relying on ambient default group

When it happens

Trigger: Calling upload_document_to_dataset with dataset_id empty/None while the RAGFLOW_DEFAULT_GROUP environment variable is unset or empty string; config loader returning a blank default.

Common situations: Fresh deployments missing the env var; docker-compose files not passing RAGFLOW_DEFAULT_GROUP into the knowledge container; .env not loaded in the service runtime.

Understand the failure class

Background: "environment variable is not set" and "Missing keys in environment" errors: what missing required env var messages mean and how to fix them — this error's family across 28 libraries.

Related errors

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

Appendix: source

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

    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"
        )
    rag = get_rag_object()

    sdk_hit: List[Any] = rag.list_datasets(name=group_name)
    if sdk_hit:
        dataset_obj = sdk_hit[0]
    else:
        logger.warning(
            "Dataset '%s' not visible via SDK lookup, refreshing via REST API",
            group_name,
        )
        dataset_obj = await _resolve_dataset_via_rest(group_name, rag)

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

View on GitHub (pinned to 5e758547a8)