{"record":{"id":"cf6e256491250872","repo":"infiniflow/ragflow","slug":"ucloud-sandbox-is-required-for-the-ucloud-agent-sa","errorCode":null,"errorMessage":"ucloud-sandbox is required for the UCloud Agent Sandbox provider.","messagePattern":"ucloud-sandbox is required for the UCloud Agent Sandbox provider\\.","errorType":"exception","errorClass":"SandboxProviderConfigError","httpStatus":null,"severity":"error","filePath":"agent/sandbox/providers/ucloud_agent_sandbox.py","lineNumber":470,"sourceCode":"            logger.warning(\"Failed to kill UCloud Agent Sandbox %s: %s\", sandbox.sandbox_id, exc)\n\n    @staticmethod\n    def _normalize_language(language: str) -> str:\n        \"\"\"Normalize supported language aliases to provider runtime names.\"\"\"\n        value = (language or \"python\").lower()\n        if value in {\"python\", \"python3\"}:\n            return \"python\"\n        if value in {\"javascript\", \"js\", \"node\", \"nodejs\"}:\n            return \"nodejs\"\n        return value\n\n\ndef _get_ucloud_sandbox_module():\n    \"\"\"Import and return the UCloud SDK with a provider-specific error.\"\"\"\n    try:\n        import ucloud_sandbox\n    except ImportError as exc:\n        raise SandboxProviderConfigError(\"ucloud-sandbox is required for the UCloud Agent Sandbox provider.\") from exc\n    return ucloud_sandbox\n","sourceCodeStart":452,"sourceCodeEnd":472,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ucloud_agent_sandbox.py#L452-L472","documentation":"Raised by `_get_ucloud_sandbox_module()` when `import ucloud_sandbox` fails with ImportError, translated to SandboxProviderConfigError. The UCloud SDK is an optional dependency (like tenki for the Tenki provider); the provider cannot run without it. This helper is called both at initialize() and again before each SDK-using operation.","triggerScenarios":"Configuring the UCloud Agent Sandbox provider in a RAGFlow runtime where the `ucloud-sandbox` package is not installed — stock Docker image, fresh venv, or an environment where the package was uninstalled.","commonSituations":"Selecting the ucloud provider from the sandbox config without adding its SDK dependency; dependency resolution dropping the package after a lock-file regeneration; deploying to a new node that never received the manual install.","solutions":["Install the SDK into the RAGFlow runtime: `pip install ucloud-sandbox` (or `uv pip install ucloud-sandbox`).","Add the package to the deployment image/requirements for the API server and sandbox worker so restarts keep it.","Restart the backend after installing so the import succeeds in a fresh process.","If UCloud is not intended, switch the provider in sandbox_conf to one whose dependencies are present."],"exampleFix":"# before\nprovider.initialize({\"api_url\": url, \"api_key\": key})  # ImportError -> SandboxProviderConfigError\n\n# after (install first: pip install ucloud-sandbox)\nprovider.initialize({\"api_url\": url, \"api_key\": key})  # import ucloud_sandbox succeeds","handlingStrategy":"validation","validationCode":"import importlib.util\n\nif importlib.util.find_spec(\"ucloud_sandbox\") is None:\n    raise SystemExit(\"Install the SDK first: pip install ucloud-sandbox\")\nprovider.initialize(conf)","typeGuard":"import importlib.util\n\ndef ucloud_sdk_available() -> bool:\n    \"\"\"True when the optional ucloud_sandbox module is importable.\"\"\"\n    return importlib.util.find_spec(\"ucloud_sandbox\") is not None","tryCatchPattern":"try:\n    provider.initialize(conf)\nexcept SandboxProviderConfigError as e:\n    if \"ucloud-sandbox is required\" in str(e):\n        raise SystemExit(\"Run: pip install ucloud-sandbox, then restart RAGFlow\") from e\n    raise","preventionTips":["Add ucloud-sandbox to the deployment image requirements when the provider is configured.","Preflight find_spec('ucloud_sandbox') during startup so the failure is loud before sessions begin.","Re-install after venv rebuilds/lock-file regeneration — optional deps drop silently otherwise."],"tags":["dependency","optional-dependency","ucloud","sandbox","configuration"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}