infiniflow/ragflow · error · RuntimeError

UCloud Agent Sandbox execution failed: {exc}

Error message

UCloud Agent Sandbox execution failed: {exc}

What it means

Generic catch-all around `sandbox.commands.run(...)`: any SDK exception that is not CommandExitException (a normal non-zero exit, which becomes the result) or TimeoutException is re-raised as RuntimeError with the original error chained. Covers transport failures, sandbox died mid-run, set_timeout failures, and unknown SDK error types.

Source

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

            raise RuntimeError(f"Execution timeout must be greater than 0 seconds, got {requested_timeout}.")
        exec_timeout = min(requested_timeout, self.timeout)
        sdk = _get_ucloud_sandbox_module()

        start_time = time.time()
        try:
            sandbox.set_timeout(max(self.sandbox_timeout, exec_timeout + 30), request_timeout=self.timeout)
            result = sandbox.commands.run(
                f"{executable} {shlex.quote(script_path)}",
                cwd=remote_work_dir,
                timeout=exec_timeout,
                request_timeout=max(self.timeout, exec_timeout),
            )
        except sdk.CommandExitException as exc:
            result = exc
        except sdk.TimeoutException as exc:
            raise TimeoutError(f"Execution timed out after {exec_timeout} seconds") from exc
        except Exception as exc:
            raise RuntimeError(f"UCloud Agent Sandbox execution failed: {exc}") from exc
        execution_time = time.time() - start_time

        stdout = result.stdout or ""
        stderr = result.stderr or ""
        exit_code = int(result.exit_code)
        self._validate_output_size(stdout, stderr)
        stdout, structured_result = extract_structured_result(stdout)

        return ExecutionResult(
            stdout=stdout,
            stderr=stderr,
            exit_code=exit_code,
            execution_time=execution_time,
            metadata={
                "instance_id": instance_id,
                "sandbox_id": sandbox.sandbox_id,
                "language": normalized_lang,
                "script_path": script_path,

View on GitHub (pinned to 554fb1133a)

Solutions

  1. Inspect `exc.__cause__` to find the real SDK failure before deciding to retry.
  2. For 'sandbox gone'/transport errors, recreate the instance and re-run the script idempotently.
  3. Keep executions well under sandbox_timeout so the VM is not reclaimed mid-command.
  4. Ensure only one component controls a given instance handle's lifecycle.

Example fix

# before
result = provider.execute(inst, code)  # opaque RuntimeError mid-run

# after
try:
    result = provider.execute(inst, code)
except RuntimeError as e:
    if "sandbox" in str(e.__cause__ or "").lower():
        inst = provider.create_instance("python")
        result = provider.execute(inst, code)
    else:
        raise
Defensive patterns

Strategy: try-catch

Validate before calling

# keep executions short relative to the sandbox lease
if int(conf.get("sandbox_timeout", 300)) <= int(conf.get("timeout", 30)):
    conf["sandbox_timeout"] = int(conf.get("timeout", 30)) + 60

Type guard

def is_recoverable_exec_error(exc: RuntimeError) -> bool:
    text = str(exc.__cause__ or exc).lower()
    return any(t in text for t in ("connection", "not found", "gone", "terminated"))

Try / catch

try:
    result = provider.execute(inst, code)
except RuntimeError as e:
    if is_recoverable_exec_error(e):
        inst = provider.create_instance("python")  # refresh dead sandbox, then rerun idempotent code
        result = provider.execute(inst, code)
    else:
        raise

Prevention

When it happens

Trigger: Sandbox VM reclaimed/killed while the command ran; network drop between RAGFlow and UCloud during execution; `sandbox.set_timeout(...)` API failing; SDK raising a novel exception type.

Common situations: Long executions outliving the sandbox VM lease; flaky networking to the UCloud gateway; executing after the sandbox was concurrently terminated by another component.

Related errors

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