iflytek/astron-agent · error · ValueError

RAGFLOW_BASE_URL not configured in environment variables

Error message

RAGFLOW_BASE_URL not configured in environment variables

What it means

get_rag_object requires RAGFLOW_BASE_URL to construct the RAGFlow SDK client. When the resolved base_url is empty (the 'base_url' config value and RAGFLOW_BASE_URL env var both unset/empty), a ValueError is raised so the SDK is never instantiated with a blank endpoint.

Solutions

Set RAGFLOW_BASE_URL in the core/knowledge service environment (e.g. http://ragflow:9380) and restart
Check docker-compose/helm env/secret wiring for the knowledge service
Confirm with `env | grep RAGFLOW` inside the running container that the variable is present and non-empty
If RAGFlow is optional in this deployment, gate the code path on configuration instead of calling it unconditionally

Example fix

# before (docker-compose.yml, knowledge service)
# environment: []
# after
environment:
  - RAGFLOW_BASE_URL=http://ragflow:9380
  - RAGFLOW_API_TOKEN=${RAGFLOW_API_TOKEN}

Defensive patterns

Strategy: validation

Validate before calling

import os
def ragflow_env_ready() -> bool:
    return bool(os.environ.get('RAGFLOW_BASE_URL', '').strip())

Try / catch

try:
    rag = get_rag_object()
except ValueError as e:
    if 'RAGFLOW_BASE_URL' in str(e):
        logger.error('RAGFlow base URL missing: %s', e)
        rag = None

Prevention

Set RAGFLOW_BASE_URL in deployment manifests before first use
Validate required RAGFlow env vars at service startup
Document required env vars in the deployment README/helm values

When it happens

Trigger: First call to any RAGFlow operation (upload_document_to_dataset, retrieval, etc.) when the environment/config in the core/knowledge process has no RAGFLOW_BASE_URL, causing get_rag_object to fail before creating the client.

Common situations: Env var not set in docker-compose/helm values; .env file not loaded; variable defined under a wrong key or in the wrong service's environment; secret/configmap mount missing in the deployed pod.

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/708688a98852a877. Report an issue: GitHub.

Appendix: source

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

_session_lock = asyncio.Lock()
_rag_object = None
_rag_object_config_key = None


def get_rag_object() -> Any:
    """
    Get or create RAGFlow client instance with proper configuration loading
    """
    global _rag_object, _rag_object_config_key
    base_url = _config_value("base_url", "RAGFLOW_BASE_URL", "")
    api_key = _config_value("api_token", "RAGFLOW_API_TOKEN", "")
    config_key = (base_url, api_key)
    if _rag_object is None or _rag_object_config_key != config_key:
        if RAGFlow is None:
            raise ImportError("ragflow_sdk is not available")

        if not base_url:
            raise ValueError("RAGFLOW_BASE_URL not configured in environment variables")
        if not api_key:
            raise ValueError(
                "RAGFLOW_API_TOKEN not configured in environment variables"
            )

        _rag_object = RAGFlow(api_key=api_key, base_url=base_url)
        _rag_object_config_key = config_key
        print(f"RAGFlow client initialized with base_url: {base_url}")

    return _rag_object


def _load_ragflow_config() -> Dict[str, Any]:
    """
    Load RAGFlow configuration from constants module (with caching)

    Returns:
        Configuration dictionary

View on GitHub (pinned to 5e758547a8)