infiniflow/ragflow · critical · SandboxProviderConfigError

paramiko is required for the SSH sandbox provider. Install t

Error message

paramiko is required for the SSH sandbox provider. Install the project dependencies to enable it.

What it means

Raised as SandboxProviderConfigError by _get_paramiko_module() when 'import paramiko' fails. paramiko is the SSH implementation this provider is built on (imported lazily under TYPE_CHECKING so the module can load without it), and the guard converts the ImportError into a actionable config error. It fires as soon as the provider tries to create an SSH client.

Source

Thrown at agent/sandbox/providers/ssh.py:685

                    "size": size,
                }
            )

    @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_paramiko_module():
    try:
        import paramiko
    except ImportError as exc:
        raise SandboxProviderConfigError("paramiko is required for the SSH sandbox provider. Install the project dependencies to enable it.") from exc
    return paramiko

View on GitHub (pinned to 554fb1133a)

Solutions

1. Install the dependency: pip install paramiko (or reinstall with the project extra that bundles it)
2. In containerized deployments, use the image variant that includes sandbox dependencies
3. If it persists, test 'python -c "import paramiko"' to see the underlying broken transitive dep (usually cryptography) and reinstall it

Example fix

# before
$ python -c "import paramiko"
ModuleNotFoundError: No module named 'paramiko'

# after
$ pip install paramiko
$ python -c "import paramiko; print(paramiko.__version__)"

try:
    import paramiko  # noqa: F401
except ImportError:
    raise RuntimeError("paramiko missing; pip install paramiko before enabling the SSH sandbox provider")

from agent.sandbox.providers.base import SandboxProviderConfigError
try:
    provider = SSHProvider()
    provider.initialize(config)
except SandboxProviderConfigError as e:
    if "paramiko is required" in str(e):
        raise RuntimeError("install sandbox deps (pip install paramiko) and redeploy") from e

When it happens

Trigger: Running RAGFlow/agent in an environment where the 'ragflow-full' (or paramiko-bearing) extra is not installed; slim Docker images that trimmed optional deps; a venv built from a minimal requirements set; Python version mismatch causing paramiko's crypto deps (cryptography) to fail to import, which surfaces as ImportError on paramiko.

Common situations: pip install of only core requirements on a fresh box; upgrading Python and reinstalling without extras; dependency conflicts removing cryptography so paramiko import chain fails.

Related errors

• Failed to load SSH private key. {errors}
• BigQuery client not installed. Please install google-cloud-b
• Invalid SSH provider configuration.
• Provider not initialized. Call initialize() first.
• Failed to create remote artifacts directory: {stderr or stdo

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