{"record":{"id":"86750a696b900062","repo":"infiniflow/ragflow","slug":"ssh-connectivity-check-failed-on-self-username","errorCode":null,"errorMessage":"SSH connectivity check failed on {self.username}@{self.host}:{self.port}: {stderr or 'remote command returned non-zero exit status'}","messagePattern":"SSH connectivity check failed on (.+?)@(.+?):(.+?): (.+?)","errorType":"exception","errorClass":"SandboxProviderConfigError","httpStatus":null,"severity":"critical","filePath":"agent/sandbox/providers/ssh.py","lineNumber":268,"sourceCode":"\n    def health_check(self) -> bool:\n        try:\n            self._assert_connectivity()\n            return True\n        except Exception:\n            return False\n\n    def _assert_connectivity(self) -> None:\n        try:\n            client = self._create_ssh_client()\n            try:\n                _, stderr, exit_code = self._run_remote_command(\n                    client,\n                    \"true\",\n                    timeout=min(self.timeout, 10),\n                )\n                if exit_code != 0:\n                    raise SandboxProviderConfigError(f\"SSH connectivity check failed on {self.username}@{self.host}:{self.port}: {stderr or 'remote command returned non-zero exit status'}\")\n            finally:\n                client.close()\n        except SandboxProviderConfigError:\n            raise\n        except Exception as exc:\n            raise SandboxProviderConfigError(f\"Failed to connect to SSH host {self.username}@{self.host}:{self.port}: {exc}\") from exc\n\n    def get_supported_languages(self) -> List[str]:\n        return [\"python\", \"javascript\", \"nodejs\"]\n\n    @staticmethod\n    def get_config_schema() -> Dict[str, Dict]:\n        return {\n            \"host\": {\n                \"type\": \"string\",\n                \"required\": True,\n                \"label\": \"SSH Host\",\n                \"placeholder\": \"192.168.1.10\",","sourceCodeStart":250,"sourceCodeEnd":286,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ssh.py#L250-L286","documentation":"Raised as SandboxProviderConfigError by SSHProvider._assert_connectivity when the SSH connection itself succeeds but running the command 'true' on the remote host returns a non-zero exit status. It means the transport works but the remote shell environment is broken, so the provider refuses to start. The message embeds user@host:port and the captured stderr (or a generic fallback).","triggerScenarios":"initialize() or create_instance() against a host whose default shell fails immediately (broken .bashrc/.profile exiting non-zero, no valid shell in /etc/passwd, restricted/forced command in authorized_keys that ignores 'true'); a login shell printout polluting stderr with a failing last command; sftp-only accounts.","commonSituations":"Hardened or chrooted SSH accounts whose forced command returns non-zero; user dotfiles that exit with an error status; managed bastion images where the shell is replaced by a wrapper; accounts restricted by rssh/sftp-only shells.","solutions":["Test manually: ssh user@host true; echo $? — if it is non-zero, fix the remote shell environment","Remove exit-non-zero statements from the account's .bashrc/.profile/.bash_profile","If the account is sftp-only or forced-command, use a full shell account for this provider","Correct the shell field in /etc/passwd (e.g. usermod -s /bin/bash user)"],"exampleFix":"// before: account shell exits 1 on login\n$ ssh deploy@10.0.0.5 true; echo $?\n1\n\n// after: fix shell startup files / shell field\n$ ssh deploy@10.0.0.5 true; echo $?\n0","handlingStrategy":"try-catch","validationCode":"import subprocess\nrc = subprocess.run([\"ssh\", f\"{user}@{host}\", \"-p\", str(port), \"true\"]).returncode\nif rc != 0:\n    raise RuntimeError(f\"remote shell broken on {host} (exit {rc}); fix shell init files\")","typeGuard":null,"tryCatchPattern":"from agent.sandbox.providers.base import SandboxProviderConfigError\ntry:\n    provider.initialize(config)\nexcept SandboxProviderConfigError as e:\n    if \"connectivity check failed\" in str(e):\n        log.error(\"remote shell exits non-zero on login; fix .bashrc/.profile or shell for the account\")\n        raise","preventionTips":["Pre-flight check 'ssh user@host true' returns 0 before wiring an account to the provider","Keep login shell init files free of non-zero exits","Use full shell accounts, not sftp-only or forced-command accounts"],"tags":["ssh","connectivity","remote-shell","configuration"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}