infiniflow/ragflow · error · RuntimeError

Unsupported language for UCloud Agent Sandbox provider: {tem

Error message

Unsupported language for UCloud Agent Sandbox provider: {template}

What it means

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.

Source

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

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

        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:

View on GitHub (pinned to 554fb1133a)

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.

Example fix

# before
handle = provider.create_instance("java")  # RuntimeError

# after
handle = provider.create_instance("python")

Defensive patterns

Strategy: type-guard

Validate before calling

SUPPORTED = {"python", "nodejs"}
aliases = {"python": "python", "python3": "python", "javascript": "nodejs", "js": "nodejs", "node": "nodejs", "nodejs": "nodejs"}
lang = aliases.get(str(template).strip().lower(), str(template).strip().lower())
if lang not in SUPPORTED:
    raise ValueError(f"Language {template!r} unsupported; use one of {sorted(SUPPORTED)}")
handle = provider.create_instance(lang)

Type guard

def is_supported_ucloud_language(template: str) -> bool:
    aliases = {"python", "python3", "javascript", "js", "node", "nodejs"}
    return str(template).strip().lower() in aliases

Try / catch

try:
    handle = provider.create_instance(template)
except RuntimeError as e:
    if "Unsupported language" in str(e):
        handle = provider.create_instance("python")  # explicit fallback choice
    else:
        raise

Prevention

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.

When it happens

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

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

Related errors

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