infiniflow/ragflow · error · SandboxProviderConfigError

UCloud Agent Sandbox authentication failed: check the API ke

Error message

UCloud Agent Sandbox authentication failed: check the API key.

What it means

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).

Source

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

        if not self._initialized:
            raise RuntimeError("Provider not initialized. Call initialize() first.")

        language = self._normalize_language(template)
        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

View on GitHub (pinned to 554fb1133a)

Solutions

1. Verify the api_key is correct and active in the UCloud console and re-inject it into the sandbox config.
2. Confirm api_url matches the environment (region/product) the key was issued for.
3. Strip whitespace/newlines from the key when loading it from env or a secrets file.
4. Catch SandboxProviderConfigError around create_instance and halt agent flows that need code execution instead of retrying — auth errors do not self-heal.

Example fix

# before
config = {"api_url": url, "api_key": "sk-stale-key\n"}  # AuthenticationException on create

# after
config = {"api_url": url, "api_key": os.environ["UCLOUD_API_KEY"].strip()}

# no API-side precheck exists; cheapest guard is a canary create at startup
def ucloud_auth_ok(provider) -> bool:
    try:
        inst = provider.create_instance("python")
        provider.destroy_instance(inst.instance_id)
        return True
    except SandboxProviderConfigError:
        return False

def looks_like_ucloud_key(key: str) -> bool:
    k = (key or "").strip()
    return bool(k) and "\n" not in k and not k.startswith("whitespace")

try:
    inst = provider.create_instance("python")
except SandboxProviderConfigError as e:
    if "authentication failed" in str(e).lower():
        alert_ops("UCloud API key rejected — rotate credentials")
    raise  # never retry auth failures in a loop

When it happens

Trigger: 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.

Common situations: 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.

Understand the failure class

• Authentication and authorization failures — expired tokens, bad credentials, and missing scopes.

Related errors

• main() must be defined or exported.
• Failed to delete memory
• Failed to update memory
• Invalid SSH provider configuration.
• Tenki authentication failed: check the API key.

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