{"record":{"id":"7efa5db8f61508ad","repo":"infiniflow/ragflow","slug":"paramiko-is-required-for-the-ssh-sandbox-provider","errorCode":null,"errorMessage":"paramiko is required for the SSH sandbox provider. Install the project dependencies to enable it.","messagePattern":"paramiko is required for the SSH sandbox provider\\. Install the project dependencies to enable it\\.","errorType":"exception","errorClass":"SandboxProviderConfigError","httpStatus":null,"severity":"critical","filePath":"agent/sandbox/providers/ssh.py","lineNumber":685,"sourceCode":"                    \"size\": size,\n                }\n            )\n\n    @staticmethod\n    def _normalize_language(language: str) -> str:\n        lang_lower = (language or \"python\").lower()\n        if lang_lower in {\"python\", \"python3\"}:\n            return \"python\"\n        if lang_lower in {\"javascript\", \"nodejs\"}:\n            return \"nodejs\"\n        return lang_lower\n\n\ndef _get_paramiko_module():\n    try:\n        import paramiko\n    except ImportError as exc:\n        raise SandboxProviderConfigError(\"paramiko is required for the SSH sandbox provider. Install the project dependencies to enable it.\") from exc\n    return paramiko\n","sourceCodeStart":667,"sourceCodeEnd":687,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ssh.py#L667-L687","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Install the dependency: pip install paramiko (or reinstall with the project extra that bundles it)","In containerized deployments, use the image variant that includes sandbox dependencies","If it persists, test 'python -c \"import paramiko\"' to see the underlying broken transitive dep (usually cryptography) and reinstall it"],"exampleFix":"# before\n$ python -c \"import paramiko\"\nModuleNotFoundError: No module named 'paramiko'\n\n# after\n$ pip install paramiko\n$ python -c \"import paramiko; print(paramiko.__version__)\"","handlingStrategy":"validation","validationCode":"try:\n    import paramiko  # noqa: F401\nexcept ImportError:\n    raise RuntimeError(\"paramiko missing; pip install paramiko before enabling the SSH sandbox provider\")","typeGuard":null,"tryCatchPattern":"from agent.sandbox.providers.base import SandboxProviderConfigError\ntry:\n    provider = SSHProvider()\n    provider.initialize(config)\nexcept SandboxProviderConfigError as e:\n    if \"paramiko is required\" in str(e):\n        raise RuntimeError(\"install sandbox deps (pip install paramiko) and redeploy\") from e","preventionTips":["Pin paramiko in the deployment environment or use the full-dependency install target","Add a startup dependency check that imports paramiko before enabling SSH sandboxes","Bake the dependency into the container image so runtime installs are never needed"],"tags":["dependencies","paramiko","installation","ssh","import-error"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}