infiniflow/ragflow · error · RuntimeError

Failed to create UCloud Agent Sandbox: {exc}

Error message

Failed to create UCloud Agent Sandbox: {exc}

What it means

The generic catch-all around `sdk.Sandbox.create(...)`: any exception from the UCloud SDK that is not AuthenticationException, RateLimitException, or TimeoutException is re-raised as RuntimeError with the original exception text chained (`from exc`). Typical causes are network/DNS/TLS failures, HTTP 5xx from the gateway, SDK bugs, or unexpected response shapes.

Source

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

        sdk = _get_ucloud_sandbox_module()
        try:
            sandbox = sdk.Sandbox.create(
                template=self.template,
                timeout=self.sandbox_timeout,
                metadata={"source": "ragflow"},
                secure=True,
                allow_internet_access=self.allow_internet_access,
                **self._api_options(),
            )
        except sdk.AuthenticationException as exc:
            raise SandboxProviderConfigError("UCloud Agent Sandbox authentication failed: check the API key.") from exc
        except sdk.RateLimitException as exc:
            raise RuntimeError(f"UCloud Agent Sandbox rate limited, please retry: {exc}") from exc
        except sdk.TimeoutException as exc:
            raise TimeoutError("Timed out while creating a UCloud Agent Sandbox.") from exc
        except Exception as exc:
            raise RuntimeError(f"Failed to create UCloud Agent Sandbox: {exc}") from exc

        remote_work_dir = posixpath.join(SANDBOX_HOME, f"ragflow-codeexec-{uuid.uuid4().hex}")
        try:
            sandbox.commands.run(
                f"mkdir -p {shlex.quote(posixpath.join(remote_work_dir, 'artifacts'))}",
                timeout=min(self.timeout, 10),
                request_timeout=self.timeout,
            )
        except Exception:
            self._safe_kill(sandbox)
            raise

        instance_id = str(uuid.uuid4())
        self._instances[instance_id] = {"sandbox": sandbox, "remote_work_dir": remote_work_dir, "language": language}
        return SandboxInstance(
            instance_id=instance_id,
            provider="ucloud_agent_sandbox",
            status="running",

View on GitHub (pinned to 554fb1133a)

Solutions

1. Inspect `exc.__cause__` / the embedded message to identify the underlying network or HTTP error.
2. Verify api_url is reachable from the RAGFlow backend container (curl the host, check DNS/egress).
3. For transient 5xx/network errors, retry with backoff; do not retry blindly for deterministic failures.
4. Pin a ucloud_sandbox SDK version tested with this provider.

Example fix

# before
inst = provider.create_instance("python")  # DNS error inside SDK -> opaque RuntimeError

# after
try:
    inst = provider.create_instance("python")
except RuntimeError as e:
    logger.error("ucloud create failed: %s", e.__cause__ or e)
    raise

import socket, urllib.parse

host = urllib.parse.urlparse(conf["api_url"]).hostname or ""
try:
    socket.getaddrinfo(host, 443)
except socket.gaierror:
    raise ValueError(f"UCloud api_url host unreachable/unresolvable: {host}")

def is_transient_create_error(exc: RuntimeError) -> bool:
    text = str(exc.__cause__ or exc).lower()
    return any(t in text for t in ("connection", "timed out", "502", "503", "504"))

try:
    inst = provider.create_instance("python")
except RuntimeError as e:
    if is_transient_create_error(e):
        backoff_and_retry(lambda: provider.create_instance("python"))
    else:
        logger.error("ucloud create failed: %s", e.__cause__ or e)
        raise

When it happens

Trigger: UCloud API unreachable (DNS failure, firewall egress block, wrong api_url host), gateway 500/502/503 responses, or SDK version incompatibilities raising custom errors not in the mapped set.

Common situations: Containers without outbound internet (allow_internet_access affects the sandbox, not the API call itself); api_url with a typo so DNS never resolves; corporate proxies intercepting TLS; ucloud_sandbox SDK upgraded with new exception types this provider does not map.

Related errors

• UCloud Agent Sandbox execution failed: {exc}
• WhatsApp session is not running.
• HTTP {response.status_code}: {response.text}
• Execution timed out after {exec_timeout} seconds
• HTTP request failed: {str(e)}

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