infiniflow/ragflow · error · SandboxProviderConfigError

Invalid UCloud Agent Sandbox configuration.

Error message

Invalid UCloud Agent Sandbox configuration.

What it means

Raised during UCloud Agent Sandbox provider initialization when `self.validate_config()` returns a not-valid verdict. It is a catch-all SandboxProviderConfigError used when the validator rejects the config (missing api_url/api_key, bad template, non-numeric timeouts, etc.) but returns an empty error message; the per-field defaults are applied just before validation.

Source

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

        Raises:
            SandboxProviderConfigError: If the configuration or SDK is invalid.
        """
        self.api_key = str(config.get("api_key", "") or "").strip()
        self.region = str(config.get("region", DEFAULT_REGION) or DEFAULT_REGION).strip()
        self.domain = str(config.get("domain", "") or "").strip()
        self.api_url = str(config.get("api_url", "") or "").strip()
        self.template = str(config.get("template", "base") or "base").strip()
        self.allow_internet_access = bool(config.get("allow_internet_access", False))
        self.insecure_http = bool(config.get("insecure_http", False))
        self.timeout = int(config.get("timeout", 30) or 30)
        self.sandbox_timeout = int(config.get("sandbox_timeout", 300) or 300)
        self.max_output_bytes = int(config.get("max_output_bytes", 1024 * 1024) or 1024 * 1024)
        self.max_artifacts = int(config.get("max_artifacts", 20) or 20)
        self.max_artifact_bytes = int(config.get("max_artifact_bytes", 10 * 1024 * 1024) or 10 * 1024 * 1024)

        is_valid, error_message = self.validate_config(config | {"api_key": self.api_key})
        if not is_valid:
            raise SandboxProviderConfigError(error_message or "Invalid UCloud Agent Sandbox configuration.")

        _get_ucloud_sandbox_module()
        self._initialized = True
        logger.info("UCloud Agent Sandbox provider initialized")
        return True

    def create_instance(self, template: str = "python") -> SandboxInstance:
        """Create a disposable sandbox and its isolated execution workspace.

        Args:
            template: Requested language identifier used to validate the runtime.

        Returns:
            A RAGFlow sandbox instance handle.
        """
        if not self._initialized:
            raise RuntimeError("Provider not initialized. Call initialize() first.")

View on GitHub (pinned to 554fb1133a)

Solutions

1. Check the validate_config rules for this provider and supply all required fields: a non-empty `api_url` and a valid `api_key` at minimum.
2. Use exact key names: api_url, api_key, template, allow_internet_access, insecure_http, timeout, sandbox_timeout, max_output_bytes, max_artifacts, max_artifact_bytes.
3. Ensure numeric settings are integers (or coercible strings), e.g. timeout=30, sandbox_timeout=300.
4. Catch SandboxProviderConfigError at startup and surface the validator's message when present so misconfiguration fails fast.

Example fix

# before
provider.initialize({"api_url": "", "api_key": "sk-..."})  # validate_config fails

# after
provider.initialize({
    "api_url": "https://ucloud.example.com",
    "api_key": os.environ["UCLOUD_API_KEY"],
    "template": "base",
    "timeout": 30,
})

required = {"api_url", "api_key"}
missing = required - {k for k in conf if str(conf.get(k, "")).strip()}
for num_key in ("timeout", "sandbox_timeout", "max_output_bytes", "max_artifacts", "max_artifact_bytes"):
    try:
        int(conf.get(num_key, 0) or 0)
    except (TypeError, ValueError):
        missing.add(num_key)
if missing:
    raise ValueError(f"Invalid UCloud config: check {sorted(missing)}")
provider.initialize(conf)

def is_valid_ucloud_conf(conf: dict) -> bool:
    return (
        isinstance(conf, dict)
        and bool(str(conf.get("api_url", "")).strip())
        and bool(str(conf.get("api_key", "")).strip())
    )

try:
    provider.initialize(conf)
except SandboxProviderConfigError as e:
    logger.error("ucloud provider misconfigured: %s", e)
    raise  # config errors are deterministic; fix the config, don't retry

When it happens

Trigger: Calling `provider.initialize(config)` where config fails validate_config — e.g. api_url empty, api_key missing, or timeout/max_output_bytes/max_artifacts set to non-integer values. Also note the fallbacks: `timeout=30`, `sandbox_timeout=300`, `max_output_bytes=1MiB` are substituted when the key is absent or falsy, so only genuinely invalid (non-coercible or failing-rule) values trip it.

Common situations: Typos in the sandbox_conf keys (`apiUrl` instead of `api_url`), forgetting to provision the UCloud API key in the environment, passing a URL with whitespace/empty string, or a template name UCloud does not recognize.

Related errors

• SANDBOX_LOCAL_TIMEOUT must be greater than 0.
• SANDBOX_LOCAL_MAX_MEMORY_MB must be greater than 0.
• SANDBOX_LOCAL_MAX_OUTPUT_BYTES must be greater than 0.
• SANDBOX_LOCAL_MAX_ARTIFACTS must be greater than or equal to
• SANDBOX_LOCAL_MAX_ARTIFACT_BYTES must be greater than 0.

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