{"record":{"id":"ca2a71d94005fe50","repo":"infiniflow/ragflow","slug":"timed-out-while-creating-a-ucloud-agent-sandbox","errorCode":null,"errorMessage":"Timed out while creating a UCloud Agent Sandbox.","messagePattern":"Timed out while creating a UCloud Agent Sandbox\\.","errorType":"exception","errorClass":"TimeoutError","httpStatus":null,"severity":"error","filePath":"agent/sandbox/providers/ucloud_agent_sandbox.py","lineNumber":130,"sourceCode":"        if language not in {\"python\", \"nodejs\"}:\n            raise RuntimeError(f\"Unsupported language for UCloud Agent Sandbox provider: {template}\")\n\n        sdk = _get_ucloud_sandbox_module()\n        try:\n            sandbox = sdk.Sandbox.create(\n                template=self.template,\n                timeout=self.sandbox_timeout,\n                metadata={\"source\": \"ragflow\"},\n                secure=True,\n                allow_internet_access=self.allow_internet_access,\n                **self._api_options(),\n            )\n        except sdk.AuthenticationException as exc:\n            raise SandboxProviderConfigError(\"UCloud Agent Sandbox authentication failed: check the API key.\") from exc\n        except sdk.RateLimitException as exc:\n            raise RuntimeError(f\"UCloud Agent Sandbox rate limited, please retry: {exc}\") from exc\n        except sdk.TimeoutException as exc:\n            raise TimeoutError(\"Timed out while creating a UCloud Agent Sandbox.\") from exc\n        except Exception as exc:\n            raise RuntimeError(f\"Failed to create UCloud Agent Sandbox: {exc}\") from exc\n\n        remote_work_dir = posixpath.join(SANDBOX_HOME, f\"ragflow-codeexec-{uuid.uuid4().hex}\")\n        try:\n            sandbox.commands.run(\n                f\"mkdir -p {shlex.quote(posixpath.join(remote_work_dir, 'artifacts'))}\",\n                timeout=min(self.timeout, 10),\n                request_timeout=self.timeout,\n            )\n        except Exception:\n            self._safe_kill(sandbox)\n            raise\n\n        instance_id = str(uuid.uuid4())\n        self._instances[instance_id] = {\"sandbox\": sandbox, \"remote_work_dir\": remote_work_dir, \"language\": language}\n        return SandboxInstance(\n            instance_id=instance_id,","sourceCodeStart":112,"sourceCodeEnd":148,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ucloud_agent_sandbox.py#L112-L148","documentation":"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.","triggerScenarios":"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`.","commonSituations":"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.","solutions":["Increase `sandbox_timeout` in the provider config (e.g. 300-600) since it governs creation, not just execution.","Retry once — cold-start provisioning delays are frequently transient.","Use a lighter/faster-booting `template` if available.","Distinguish this from execution timeout: this one fires in create_instance, before any user code runs."],"exampleFix":"# before\nconfig = {\"api_url\": url, \"api_key\": key, \"sandbox_timeout\": 30}  # creation exceeds 30s\n\n# after\nconfig = {\"api_url\": url, \"api_key\": key, \"sandbox_timeout\": 300}","handlingStrategy":"retry","validationCode":"if int(conf.get(\"sandbox_timeout\", 300) or 300) < 120:\n    # creation uses sandbox_timeout; give slow templates headroom\n    conf[\"sandbox_timeout\"] = 300","typeGuard":"def is_creation_timeout(exc: TimeoutError) -> bool:\n    return \"creating a UCloud\" in str(exc)","tryCatchPattern":"try:\n    inst = provider.create_instance(\"python\")\nexcept TimeoutError:\n    time.sleep(5)\n    inst = provider.create_instance(\"python\")  # one retry: cold starts are often transient","preventionTips":["Keep sandbox_timeout >= 300 when using non-trivial templates; it governs provisioning, not per-command time.","Distinguish creation TimeoutError from execution TimeoutError by message before choosing a fix.","Prefer lightweight templates to keep cold-start provisioning fast."],"tags":["timeout","ucloud","sandbox","provisioning","performance"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}