{"record":{"id":"8fba10b29d115039","repo":"iflytek/astron-agent","slug":"ragflow-sdk-is-not-available","errorCode":null,"errorMessage":"ragflow_sdk is not available","messagePattern":"ragflow_sdk is not available","errorType":"exception","errorClass":"ImportError","httpStatus":null,"severity":"error","filePath":"core/knowledge/infra/ragflow/ragflow_client.py","lineNumber":57,"sourceCode":"_config_cache = None\n_session_cache = None\n_session_config_key = None\n_session_lock = asyncio.Lock()\n_rag_object = None\n_rag_object_config_key = None\n\n\ndef get_rag_object() -> Any:\n    \"\"\"\n    Get or create RAGFlow client instance with proper configuration loading\n    \"\"\"\n    global _rag_object, _rag_object_config_key\n    base_url = _config_value(\"base_url\", \"RAGFLOW_BASE_URL\", \"\")\n    api_key = _config_value(\"api_token\", \"RAGFLOW_API_TOKEN\", \"\")\n    config_key = (base_url, api_key)\n    if _rag_object is None or _rag_object_config_key != config_key:\n        if RAGFlow is None:\n            raise ImportError(\"ragflow_sdk is not available\")\n\n        if not base_url:\n            raise ValueError(\"RAGFLOW_BASE_URL not configured in environment variables\")\n        if not api_key:\n            raise ValueError(\n                \"RAGFLOW_API_TOKEN not configured in environment variables\"\n            )\n\n        _rag_object = RAGFlow(api_key=api_key, base_url=base_url)\n        _rag_object_config_key = config_key\n        print(f\"RAGFlow client initialized with base_url: {base_url}\")\n\n    return _rag_object\n\n\ndef _load_ragflow_config() -> Dict[str, Any]:\n    \"\"\"\n    Load RAGFlow configuration from constants module (with caching)","sourceCodeStart":39,"sourceCodeEnd":75,"githubUrl":"https://github.com/iflytek/astron-agent/blob/5e758547a83371a5a4b29dadf4ac03e8dd527635/core/knowledge/infra/ragflow/ragflow_client.py#L39-L75","documentation":"get_rag_object in core/knowledge/infra/ragflow/ragflow_client.py lazily constructs a cached RAGFlow SDK client. The `ragflow_sdk` package is imported defensively (RAGFlow may be None); if it was not installed and a RAGFlow client is requested, an ImportError('ragflow_sdk is not available') is raised rather than failing with a cryptic NameError.","triggerScenarios":"Calling any RAGFlow-dependent function (upload_document_to_dataset, _upload_via_default_group, retrieval, dataset CRUD) in an environment where the ragflow_sdk optional dependency is not installed.","commonSituations":"Deploying core/knowledge without the ragflow extra (pip install without [ragflow]); slim Docker image excluding the SDK; requirement pin removed; venv mismatch where the service runs outside the intended environment.","solutions":["Install the optional dependency: pip install ragflow_sdk (or the project's ragflow extra)","Rebuild/redeploy the core/knowledge image with the ragflow dependency included","Verify the interpreter the service runs with actually has the package (pip show ragflow_sdk inside the container)","If RAGFlow is not needed, disable the RAGFlow-backed code path via configuration instead of calling it"],"exampleFix":"# before\npip install -r requirements.txt\n# after\npip install -r requirements.txt ragflow_sdk  # or: pip install .[ragflow]","handlingStrategy":"validation","validationCode":"import importlib.util\ndef ragflow_sdk_installed() -> bool:\n    return importlib.util.find_spec('ragflow_sdk') is not None","typeGuard":null,"tryCatchPattern":"try:\n    rag = get_rag_object()\nexcept ImportError:\n    logger.error('ragflow_sdk missing; install it or disable RAGFlow features')\n    rag = None","preventionTips":["Include ragflow_sdk in the service's requirements/extra and Docker image","Add a startup check that fails fast when a configured backend's SDK is missing","Use the same install spec in CI and production images"],"tags":["python","import","missing-dependency","ragflow"],"backgroundTag":"missing-optional-dependency","analyzedSha":"5e758547a83371a5a4b29dadf4ac03e8dd527635","analyzedAt":"2026-09-12T08:03:51.356Z","contentChangedAt":"2026-09-12T08:03:51.356Z","schemaVersion":2},"datasetVersion":"2026-09-15T23:17:13.987Z"}