{"record":{"id":"3a88084257255844","repo":"infiniflow/ragflow","slug":"invalid-ucloud-agent-sandbox-configuration","errorCode":null,"errorMessage":"Invalid UCloud Agent Sandbox configuration.","messagePattern":"Invalid UCloud Agent Sandbox configuration\\.","errorType":"exception","errorClass":"SandboxProviderConfigError","httpStatus":null,"severity":"error","filePath":"agent/sandbox/providers/ucloud_agent_sandbox.py","lineNumber":92,"sourceCode":"        Raises:\n            SandboxProviderConfigError: If the configuration or SDK is invalid.\n        \"\"\"\n        self.api_key = str(config.get(\"api_key\", \"\") or \"\").strip()\n        self.region = str(config.get(\"region\", DEFAULT_REGION) or DEFAULT_REGION).strip()\n        self.domain = str(config.get(\"domain\", \"\") or \"\").strip()\n        self.api_url = str(config.get(\"api_url\", \"\") or \"\").strip()\n        self.template = str(config.get(\"template\", \"base\") or \"base\").strip()\n        self.allow_internet_access = bool(config.get(\"allow_internet_access\", False))\n        self.insecure_http = bool(config.get(\"insecure_http\", False))\n        self.timeout = int(config.get(\"timeout\", 30) or 30)\n        self.sandbox_timeout = int(config.get(\"sandbox_timeout\", 300) or 300)\n        self.max_output_bytes = int(config.get(\"max_output_bytes\", 1024 * 1024) or 1024 * 1024)\n        self.max_artifacts = int(config.get(\"max_artifacts\", 20) or 20)\n        self.max_artifact_bytes = int(config.get(\"max_artifact_bytes\", 10 * 1024 * 1024) or 10 * 1024 * 1024)\n\n        is_valid, error_message = self.validate_config(config | {\"api_key\": self.api_key})\n        if not is_valid:\n            raise SandboxProviderConfigError(error_message or \"Invalid UCloud Agent Sandbox configuration.\")\n\n        _get_ucloud_sandbox_module()\n        self._initialized = True\n        logger.info(\"UCloud Agent Sandbox provider initialized\")\n        return True\n\n    def create_instance(self, template: str = \"python\") -> SandboxInstance:\n        \"\"\"Create a disposable sandbox and its isolated execution workspace.\n\n        Args:\n            template: Requested language identifier used to validate the runtime.\n\n        Returns:\n            A RAGFlow sandbox instance handle.\n        \"\"\"\n        if not self._initialized:\n            raise RuntimeError(\"Provider not initialized. Call initialize() first.\")\n","sourceCodeStart":74,"sourceCodeEnd":110,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ucloud_agent_sandbox.py#L74-L110","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["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.","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.","Ensure numeric settings are integers (or coercible strings), e.g. timeout=30, sandbox_timeout=300.","Catch SandboxProviderConfigError at startup and surface the validator's message when present so misconfiguration fails fast."],"exampleFix":"# before\nprovider.initialize({\"api_url\": \"\", \"api_key\": \"sk-...\"})  # validate_config fails\n\n# after\nprovider.initialize({\n    \"api_url\": \"https://ucloud.example.com\",\n    \"api_key\": os.environ[\"UCLOUD_API_KEY\"],\n    \"template\": \"base\",\n    \"timeout\": 30,\n})","handlingStrategy":"validation","validationCode":"required = {\"api_url\", \"api_key\"}\nmissing = required - {k for k in conf if str(conf.get(k, \"\")).strip()}\nfor num_key in (\"timeout\", \"sandbox_timeout\", \"max_output_bytes\", \"max_artifacts\", \"max_artifact_bytes\"):\n    try:\n        int(conf.get(num_key, 0) or 0)\n    except (TypeError, ValueError):\n        missing.add(num_key)\nif missing:\n    raise ValueError(f\"Invalid UCloud config: check {sorted(missing)}\")\nprovider.initialize(conf)","typeGuard":"def is_valid_ucloud_conf(conf: dict) -> bool:\n    return (\n        isinstance(conf, dict)\n        and bool(str(conf.get(\"api_url\", \"\")).strip())\n        and bool(str(conf.get(\"api_key\", \"\")).strip())\n    )","tryCatchPattern":"try:\n    provider.initialize(conf)\nexcept SandboxProviderConfigError as e:\n    logger.error(\"ucloud provider misconfigured: %s\", e)\n    raise  # config errors are deterministic; fix the config, don't retry","preventionTips":["Validate api_url/api_key presence at startup and fail fast before any agent session starts.","Load credentials from env/secrets and .strip() them to avoid whitespace-induced validation failures.","Keep an integration test that calls initialize() with a dummy config to catch config-schema drift on upgrade."],"tags":["configuration","sandbox","ucloud","validation","startup"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}