infiniflow/ragflow · error · SandboxProviderConfigError

tenki is required for the Tenki sandbox provider. Install it

Error message

tenki is required for the Tenki sandbox provider. Install it with `pip install tenki` (or `uv pip install tenki`).

What it means

Raised by the Tenki sandbox provider when it cannot import the optional Python package `tenki` (imported as `tenki_sandbox`). RAGFlow deliberately keeps tenki out of core dependencies because it requires protobuf>=6.31, which conflicts with RAGFlow's pinned gRPC stack, so the provider only works when the operator installs it manually into the runtime.

Source

Thrown at agent/sandbox/providers/tenki.py:520

    @staticmethod
    def _normalize_language(language: str) -> str:
        lang_lower = (language or "python").lower()
        if lang_lower in {"python", "python3"}:
            return "python"
        if lang_lower in {"javascript", "nodejs"}:
            return "nodejs"
        return lang_lower


def _get_tenki_module():
    try:
        import tenki_sandbox
    except ImportError as exc:
        # tenki is an optional dependency: it requires protobuf>=6.31,
        # which conflicts with RAGFlow's pinned gRPC stack, so it is not a core
        # dependency. Install it into the runtime to enable this provider.
        raise SandboxProviderConfigError("tenki is required for the Tenki sandbox provider. Install it with `pip install tenki` (or `uv pip install tenki`).") from exc
    return tenki_sandbox

View on GitHub (pinned to 554fb1133a)

Solutions

Install the package into the active runtime: `pip install tenki` (or `uv pip install tenki` if using uv).
If pip refuses due to the protobuf pin conflict, install tenki into a separate venv/container or relax the protobuf pin after verifying gRPC compatibility.
Restart the RAGFlow backend (API server / sandbox worker) so the new import is visible to the provider process.
If you did not intend to use Tenki, switch the sandbox provider config back to another provider (e.g. the default code executor).

Example fix

# before
sandbox_conf = {"provider": "tenki"}  # ImportError -> SandboxProviderConfigError at runtime

# after (install first: uv pip install tenki)
sandbox_conf = {"provider": "tenki"}  # import tenki_sandbox now succeeds

Defensive patterns

Strategy: validation

Validate before calling

import importlib.util

def tenki_available() -> bool:
    return importlib.util.find_spec("tenki_sandbox") is not None

# before enabling the provider
if not tenki_available():
    raise SystemExit("Install tenki first: uv pip install tenki")

Type guard

import importlib.util

def tenki_available() -> bool:
    """True when the optional tenki_sandbox module is importable."""
    return importlib.util.find_spec("tenki_sandbox") is not None

Try / catch

try:
    provider.initialize(conf)
except SandboxProviderConfigError as e:
    if "tenki is required" in str(e):
        # report install instructions, do not retry
        raise SystemExit(str(e)) from e
    raise

Prevention

Bake `tenki` into the deployment image/requirements when the Tenki provider is part of your config.
Check importlib.util.find_spec('tenki_sandbox') during startup preflight before selecting the provider.
Remember the protobuf>=6.31 constraint conflicts with RAGFlow's pinned gRPC stack — test dependency resolution after installing.

When it happens

Trigger: Selecting the Tenki provider for code execution (agent sandbox config) in an environment where `import tenki_sandbox` raises ImportError — e.g. fresh RAGFlow install, slim Docker image, or a venv where tenki was never added.

Common situations: Enabling the Tenki sandbox provider after seeing it listed in the UI without reading the optional-dependency note; upgrading RAGFlow into a new virtualenv that drops manually installed packages; dependency resolver removing tenki because of the protobuf/gRPC conflict.

Related errors

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