{"record":{"id":"a9eaba28030f1988","repo":"infiniflow/ragflow","slug":"failed-to-create-ucloud-agent-sandbox-exc","errorCode":null,"errorMessage":"Failed to create UCloud Agent Sandbox: {exc}","messagePattern":"Failed to create UCloud Agent Sandbox: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"agent/sandbox/providers/ucloud_agent_sandbox.py","lineNumber":132,"sourceCode":"\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,\n            provider=\"ucloud_agent_sandbox\",\n            status=\"running\",","sourceCodeStart":114,"sourceCodeEnd":150,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ucloud_agent_sandbox.py#L114-L150","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect `exc.__cause__` / the embedded message to identify the underlying network or HTTP error.","Verify api_url is reachable from the RAGFlow backend container (curl the host, check DNS/egress).","For transient 5xx/network errors, retry with backoff; do not retry blindly for deterministic failures.","Pin a ucloud_sandbox SDK version tested with this provider."],"exampleFix":"# before\ninst = provider.create_instance(\"python\")  # DNS error inside SDK -> opaque RuntimeError\n\n# after\ntry:\n    inst = provider.create_instance(\"python\")\nexcept RuntimeError as e:\n    logger.error(\"ucloud create failed: %s\", e.__cause__ or e)\n    raise","handlingStrategy":"try-catch","validationCode":"import socket, urllib.parse\n\nhost = urllib.parse.urlparse(conf[\"api_url\"]).hostname or \"\"\ntry:\n    socket.getaddrinfo(host, 443)\nexcept socket.gaierror:\n    raise ValueError(f\"UCloud api_url host unreachable/unresolvable: {host}\")","typeGuard":"def is_transient_create_error(exc: RuntimeError) -> bool:\n    text = str(exc.__cause__ or exc).lower()\n    return any(t in text for t in (\"connection\", \"timed out\", \"502\", \"503\", \"504\"))","tryCatchPattern":"try:\n    inst = provider.create_instance(\"python\")\nexcept RuntimeError as e:\n    if is_transient_create_error(e):\n        backoff_and_retry(lambda: provider.create_instance(\"python\"))\n    else:\n        logger.error(\"ucloud create failed: %s\", e.__cause__ or e)\n        raise","preventionTips":["Verify egress/DNS from the RAGFlow container to api_url before enabling the provider.","Always log e.__cause__ — the wrapped SDK exception carries the actionable detail.","Pin the ucloud-sandbox SDK version so unmapped exception types don't surprise you."],"tags":["network","ucloud","sandbox","sdk","catch-all"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}