{"record":{"id":"1efa2790a3ce8b64","repo":"infiniflow/ragflow","slug":"ucloud-agent-sandbox-authentication-failed-check","errorCode":null,"errorMessage":"UCloud Agent Sandbox authentication failed: check the API key.","messagePattern":"UCloud Agent Sandbox authentication failed: check the API key\\.","errorType":"exception","errorClass":"SandboxProviderConfigError","httpStatus":null,"severity":"error","filePath":"agent/sandbox/providers/ucloud_agent_sandbox.py","lineNumber":126,"sourceCode":"        if not self._initialized:\n            raise RuntimeError(\"Provider not initialized. Call initialize() first.\")\n\n        language = self._normalize_language(template)\n        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","sourceCodeStart":108,"sourceCodeEnd":144,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ucloud_agent_sandbox.py#L108-L144","documentation":"Raised when `sdk.Sandbox.create(...)` on the UCloud Agent Sandbox service raises `sdk.AuthenticationException`, translated into a SandboxProviderConfigError. It means the request reached UCloud but the API key was rejected (invalid, revoked, or wrong key for that endpoint).","triggerScenarios":"provider.initialize() succeeded structurally but create_instance() is called with an expired/incorrect api_key, a key from a different UCloud project/environment, or when `insecure_http`/api_url mismatch causes the gateway to reject credentials.","commonSituations":"Rotated or revoked API keys after a security review; key copied with trailing whitespace/newline from a secrets manager; using a production key against a staging api_url; key never injected into the container environment.","solutions":["Verify the api_key is correct and active in the UCloud console and re-inject it into the sandbox config.","Confirm api_url matches the environment (region/product) the key was issued for.","Strip whitespace/newlines from the key when loading it from env or a secrets file.","Catch SandboxProviderConfigError around create_instance and halt agent flows that need code execution instead of retrying — auth errors do not self-heal."],"exampleFix":"# before\nconfig = {\"api_url\": url, \"api_key\": \"sk-stale-key\\n\"}  # AuthenticationException on create\n\n# after\nconfig = {\"api_url\": url, \"api_key\": os.environ[\"UCLOUD_API_KEY\"].strip()}","handlingStrategy":"try-catch","validationCode":"# no API-side precheck exists; cheapest guard is a canary create at startup\ndef ucloud_auth_ok(provider) -> bool:\n    try:\n        inst = provider.create_instance(\"python\")\n        provider.destroy_instance(inst.instance_id)\n        return True\n    except SandboxProviderConfigError:\n        return False","typeGuard":"def looks_like_ucloud_key(key: str) -> bool:\n    k = (key or \"\").strip()\n    return bool(k) and \"\\n\" not in k and not k.startswith(\"whitespace\")","tryCatchPattern":"try:\n    inst = provider.create_instance(\"python\")\nexcept SandboxProviderConfigError as e:\n    if \"authentication failed\" in str(e).lower():\n        alert_ops(\"UCloud API key rejected — rotate credentials\")\n    raise  # never retry auth failures in a loop","preventionTips":["Strip() keys when loading from env or secret managers.","Run a canary create_instance during deploy preflight so bad keys fail the deploy, not user sessions.","Keep api_url and api_key paired per environment to avoid cross-environment credential mixups."],"tags":["authentication","api-key","ucloud","sandbox","credentials"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}