{"record":{"id":"5405b029c17176b6","repo":"infiniflow/ragflow","slug":"unsupported-language-for-ucloud-agent-sandbox-prov","errorCode":null,"errorMessage":"Unsupported language for UCloud Agent Sandbox provider: {template}","messagePattern":"Unsupported language for UCloud Agent Sandbox provider: (.+?)","errorType":"validation","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"agent/sandbox/providers/ucloud_agent_sandbox.py","lineNumber":113,"sourceCode":"        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\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:","sourceCodeStart":95,"sourceCodeEnd":131,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ucloud_agent_sandbox.py#L95-L131","documentation":"Raised by `create_instance(template)` when the requested language, after `_normalize_language`, is not in the provider's supported set {\"python\", \"nodejs\"}. _normalize_language maps python/python3 -> python and javascript/js/node/nodejs -> nodejs; anything else passes through unchanged and is rejected here.","triggerScenarios":"Calling `create_instance(\"java\")`, `create_instance(\"golang\")`, or `create_instance(\"bash\")`; also passing a locale-style string like \"python3.11\" (not normalized) or an empty template string.","commonSituations":"Agent canvas code-execution components configured with a language the UCloud provider never implemented; upstream code sending 'js' works but sending 'ts'/'typescript' fails; default template string from a form field left as an unsupported value.","solutions":["Use \"python\" (or python3) or \"nodejs\" (or javascript/js/node) as the template argument.","If you need another language, switch to a different sandbox provider that supports it.","Normalize the language at the call site before invoking create_instance (see type guard below).","File a feature request / extend _normalize_language if a common alias (e.g. typescript) keeps slipping through."],"exampleFix":"# before\nhandle = provider.create_instance(\"java\")  # RuntimeError\n\n# after\nhandle = provider.create_instance(\"python\")","handlingStrategy":"type-guard","validationCode":"SUPPORTED = {\"python\", \"nodejs\"}\naliases = {\"python\": \"python\", \"python3\": \"python\", \"javascript\": \"nodejs\", \"js\": \"nodejs\", \"node\": \"nodejs\", \"nodejs\": \"nodejs\"}\nlang = aliases.get(str(template).strip().lower(), str(template).strip().lower())\nif lang not in SUPPORTED:\n    raise ValueError(f\"Language {template!r} unsupported; use one of {sorted(SUPPORTED)}\")\nhandle = provider.create_instance(lang)","typeGuard":"def is_supported_ucloud_language(template: str) -> bool:\n    aliases = {\"python\", \"python3\", \"javascript\", \"js\", \"node\", \"nodejs\"}\n    return str(template).strip().lower() in aliases","tryCatchPattern":"try:\n    handle = provider.create_instance(template)\nexcept RuntimeError as e:\n    if \"Unsupported language\" in str(e):\n        handle = provider.create_instance(\"python\")  # explicit fallback choice\n    else:\n        raise","preventionTips":["Normalize language strings at your own boundary (lowercase + alias map) before calling create_instance.","Expose only a python/nodejs selector in agent UIs instead of a free-text language field.","Log the raw template value when rejection happens — silent upstream case/format differences are the usual culprit."],"tags":["sandbox","ucloud","language","validation","unsupported"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}