infiniflow/ragflow · error · TimeoutError

Timed out while creating a UCloud Agent Sandbox.

Error message

Timed out while creating a UCloud Agent Sandbox.

What it means

Raised when `sdk.Sandbox.create(...)` raises `sdk.TimeoutException`, translated to a built-in TimeoutError. The UCloud service took longer than the configured `sandbox_timeout` (default 300s) to provision the sandbox VM/workspace.

Source

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

        if language not in {"python", "nodejs"}:
            raise RuntimeError(f"Unsupported language for UCloud Agent Sandbox provider: {template}")

        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,

View on GitHub (pinned to 554fb1133a)

Solutions

1. Increase `sandbox_timeout` in the provider config (e.g. 300-600) since it governs creation, not just execution.
2. Retry once — cold-start provisioning delays are frequently transient.
3. Use a lighter/faster-booting `template` if available.
4. Distinguish this from execution timeout: this one fires in create_instance, before any user code runs.

Example fix

# before
config = {"api_url": url, "api_key": key, "sandbox_timeout": 30}  # creation exceeds 30s

# after
config = {"api_url": url, "api_key": key, "sandbox_timeout": 300}

if int(conf.get("sandbox_timeout", 300) or 300) < 120:
    # creation uses sandbox_timeout; give slow templates headroom
    conf["sandbox_timeout"] = 300

def is_creation_timeout(exc: TimeoutError) -> bool:
    return "creating a UCloud" in str(exc)

try:
    inst = provider.create_instance("python")
except TimeoutError:
    time.sleep(5)
    inst = provider.create_instance("python")  # one retry: cold starts are often transient

When it happens

Trigger: Provisioning a sandbox image (template) that is slow to boot, UCloud capacity issues, or a sandbox_timeout configured too low for the chosen template; create uses `timeout=self.sandbox_timeout`, not the per-command `timeout`.

Common situations: Large base images or cold-start capacity on the UCloud side; setting sandbox_timeout aggressively low (e.g. 30) to 'fail fast' while the template needs ~60s to provision; regional service degradation.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• Execution timeout must be greater than 0 seconds, got {reque
• Execution timed out after {exec_timeout} seconds
• Execution timed out after {exec_timeout} seconds
• Execution timeout must be greater than 0 seconds, got {reque
• Execution timed out after {exec_timeout} seconds

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