infiniflow/ragflow · error · SandboxProviderConfigError

Invalid SSH provider configuration.

Error message

Invalid SSH provider configuration.

What it means

Raised by SSHProvider.initialize() when validate_config() rejects the assembled config and returns no specific error message. The provider then raises SandboxProviderConfigError with this generic text. validate_config checks the SSH connection parameters (host, port, username, and password/private_key auth material), so this fires when required fields are missing or the auth combination is incomplete — before _assert_connectivity() ever opens a connection.

Source

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

        is_valid, error_message = self.validate_config(
            {
                "host": self.host,
                "port": self.port,
                "username": self.username,
                "password": self.password,
                "private_key": self.private_key,
                "passphrase": self.passphrase,
                "python_bin": self.python_bin,
                "node_bin": self.node_bin,
                "work_dir": self.work_dir,
                "timeout": self.timeout,
                "max_output_bytes": self.max_output_bytes,
                "max_artifacts": self.max_artifacts,
                "max_artifact_bytes": self.max_artifact_bytes,
            }
        )
        if not is_valid:
            raise SandboxProviderConfigError(error_message or "Invalid SSH provider configuration.")

        self._assert_connectivity()

        self._initialized = True
        return True

    def create_instance(self, template: str = "python") -> SandboxInstance:
        if not self._initialized:
            raise RuntimeError("Provider not initialized. Call initialize() first.")

        language = self._normalize_language(template)
        client = self._create_ssh_client()
        sftp = client.open_sftp()

        try:
            remote_work_dir = self._create_remote_workspace(client)
            stdout, stderr, exit_code = self._run_remote_command(
                client,

View on GitHub (pinned to 554fb1133a)

Solutions

1. Ensure initialize() config includes non-empty 'host', 'username', and exactly one auth path: 'password' or 'private_key' (with optional 'passphrase').
2. Validate and fail early in your own code: check required keys before calling initialize() so you can emit which field is missing.
3. Check the env/secrets source (e.g. SSH_HOST, SSH_USER, SSH_PRIVATE_KEY) is set in the runtime environment.
4. Confirm key names match the schema in get_config_schema(); a typo'd key silently leaves the field empty.

Example fix

# before
provider.initialize({"host": "", "username": "root"})

# after
provider.initialize({
    "host": "10.0.0.5",
    "port": 22,
    "username": "runner",
    "private_key": "-----BEGIN OPENSSH PRIVATE KEY-----...",
})

def valid_ssh_config(cfg: dict) -> bool:
    return bool(
        str(cfg.get("host", "")).strip()
        and str(cfg.get("username", "")).strip()
        and (cfg.get("password") or cfg.get("private_key"))
    )

assert valid_ssh_config(config), "SSH config missing host/username/auth"

def has_ssh_auth(cfg: dict) -> bool:
    """True when the config carries exactly one usable SSH auth path."""
    return bool(cfg.get("password")) != bool(cfg.get("private_key"))

try:
    provider.initialize(config)
except SandboxProviderConfigError as e:
    raise ValueError(f"SSH provider misconfigured: {e}") from e

When it happens

Trigger: Calling initialize() with empty 'host' or 'username'; providing neither 'password' nor 'private_key'; passing a port of 0 or a non-numeric port; whitespace-only credential strings after .strip().

Common situations: Env vars for SSH credentials unset in the deployment (empty strings); a secrets manager returning None rendered as ''; switching from password auth to key auth and forgetting to populate private_key; config keys misnamed (hostname instead of host).

Related errors

• main() returned a non-JSON-serializable value.
• message.compileNotSupported
• Failed to fetch search detail
• SANDBOX_LOCAL_TIMEOUT must be greater than 0.
• SANDBOX_LOCAL_MAX_MEMORY_MB must be greater than 0.

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