infiniflow/ragflow · error · SandboxProviderConfigError

ucloud-sandbox is required for the UCloud Agent Sandbox prov

Error message

ucloud-sandbox is required for the UCloud Agent Sandbox provider.

What it means

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.

Source

Thrown at agent/sandbox/providers/ucloud_agent_sandbox.py:470

            logger.warning("Failed to kill UCloud Agent Sandbox %s: %s", sandbox.sandbox_id, exc)

    @staticmethod
    def _normalize_language(language: str) -> str:
        """Normalize supported language aliases to provider runtime names."""
        value = (language or "python").lower()
        if value in {"python", "python3"}:
            return "python"
        if value in {"javascript", "js", "node", "nodejs"}:
            return "nodejs"
        return value


def _get_ucloud_sandbox_module():
    """Import and return the UCloud SDK with a provider-specific error."""
    try:
        import ucloud_sandbox
    except ImportError as exc:
        raise SandboxProviderConfigError("ucloud-sandbox is required for the UCloud Agent Sandbox provider.") from exc
    return ucloud_sandbox

View on GitHub (pinned to 554fb1133a)

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.

Example fix

# before
provider.initialize({"api_url": url, "api_key": key})  # ImportError -> SandboxProviderConfigError

# after (install first: pip install ucloud-sandbox)
provider.initialize({"api_url": url, "api_key": key})  # import ucloud_sandbox succeeds

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

if importlib.util.find_spec("ucloud_sandbox") is None:
    raise SystemExit("Install the SDK first: pip install ucloud-sandbox")
provider.initialize(conf)

Type guard

import importlib.util

def ucloud_sdk_available() -> bool:
    """True when the optional ucloud_sandbox module is importable."""
    return importlib.util.find_spec("ucloud_sandbox") is not None

Try / catch

try:
    provider.initialize(conf)
except SandboxProviderConfigError as e:
    if "ucloud-sandbox is required" in str(e):
        raise SystemExit("Run: pip install ucloud-sandbox, then restart RAGFlow") from e
    raise

Prevention

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.

When it happens

Trigger: 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.

Common situations: 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.

Related errors

AI-assisted analysis of infiniflow/ragflow@554fb1133a (2026-08-15). Data as JSON: /api/errors/cf6e256491250872. Report an issue: GitHub.