iflytek/astron-agent · error · ValueError

RAGFLOW_API_TOKEN not configured in environment variables

Error message

RAGFLOW_API_TOKEN not configured in environment variables

What it means

get_rag_object also requires an API token: if RAGFLOW_API_TOKEN (or the 'api_token' config value) is empty, it raises ValueError so the RAGFlow SDK is never created without credentials. This is the authentication half of the client-construction guard, parallel to the base-URL check.

Solutions

Generate an API key in the RAGFlow web UI and set RAGFLOW_API_TOKEN in the service environment
Check the Kubernetes secret/configmap actually contains the token under the expected key
Restart the knowledge service after adding the variable (get_rag_object caches per config key but construction happens on first use)
Verify inside the container: env | grep RAGFLOW_API_TOKEN

Example fix

# before
RAGFLOW_API_TOKEN=
# after
RAGFLOW_API_TOKEN=ragflow-xxxxxxxxxxxxxxxx

Defensive patterns

Strategy: validation

Validate before calling

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

Try / catch

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

Prevention

Store RAGFLOW_API_TOKEN in a secret manager and mount it into the service
Generate the token from the same RAGFlow instance as RAGFLOW_BASE_URL
Check credential presence in readiness probes

When it happens

Trigger: First RAGFlow SDK call when RAGFLOW_API_TOKEN is unset or empty in the core/knowledge process environment, even if RAGFLOW_BASE_URL is correctly configured.

Common situations: API token generated in the RAGFlow UI but never added to deployment secrets; token key rotated/renamed in helm values; secret mounted but with wrong key name; token left as empty placeholder in .env.

Understand the failure class

Background: "API key is required" / "API key not found" / "No API key was set": the missing-api-key error family across 16 libraries — this error's family across 16 libraries.

Related errors

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

Appendix: source

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

_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
    """
    global _config_cache

View on GitHub (pinned to 5e758547a8)