{"record":{"id":"541dcd455ecee7b0","repo":"infiniflow/ragflow","slug":"unknown-ssh-sandbox-instance-instance-id","errorCode":null,"errorMessage":"Unknown SSH sandbox instance: {instance_id}","messagePattern":"Unknown SSH sandbox instance: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"agent/sandbox/providers/ssh.py","lineNumber":170,"sourceCode":"        return SandboxInstance(\n            instance_id=instance_id,\n            provider=\"ssh\",\n            status=\"running\",\n            metadata={\"language\": language, \"remote_work_dir\": remote_work_dir},\n        )\n\n    def execute_code(\n        self,\n        instance_id: str,\n        code: str,\n        language: str,\n        timeout: int = 10,\n        arguments: Optional[Dict[str, Any]] = None,\n    ) -> ExecutionResult:\n        if not self._initialized:\n            raise RuntimeError(\"Provider not initialized. Call initialize() first.\")\n        if instance_id not in self._instances:\n            raise RuntimeError(f\"Unknown SSH sandbox instance: {instance_id}\")\n\n        normalized_lang = self._normalize_language(language)\n        instance = self._instances[instance_id]\n        client: paramiko.SSHClient = instance[\"client\"]\n        sftp: paramiko.SFTPClient = instance[\"sftp\"]\n        remote_work_dir: str = instance[\"remote_work_dir\"]\n\n        args_json = json.dumps(arguments or {}, ensure_ascii=False)\n        remote_script_path, command = self._upload_script(\n            sftp=sftp,\n            remote_work_dir=remote_work_dir,\n            language=normalized_lang,\n            code=code,\n            args_json=args_json,\n        )\n\n        requested_timeout = self.timeout if timeout is None else int(timeout)\n        if requested_timeout <= 0:","sourceCodeStart":152,"sourceCodeEnd":188,"githubUrl":"https://github.com/infiniflow/ragflow/blob/554fb1133ac3861732235ad9c377eb5e0a770665/agent/sandbox/providers/ssh.py#L152-L188","documentation":"Raised by SSHProvider.execute_code when the passed instance_id is not a key in the provider's in-memory _instances dict. Instances are created by the provider's instance-creation call, which opens the SSH/SFTP clients and a remote mktemp workspace; only those registered IDs are executable. The guard prevents operating on an unknown or already-destroyed sandbox.","triggerScenarios":"Passing a hardcoded or randomly generated instance_id instead of the ID returned by create_instance; calling execute_code after destroy/cleanup removed the instance; using an ID from a different provider instance or after a process restart (the dict is in-memory only); typo in the ID string.","commonSituations":"Agent code persisting an instance ID across service restarts (state is not durable); two providers configured for different hosts and IDs mixed up between them; retry logic reusing an ID after the instance was destroyed on failure.","solutions":["Use the exact instance_id returned by the provider's create-instance call and thread it through to execute_code","Re-create the instance (create_instance) if it was destroyed or if the process restarted, since _instances is memory-only","Verify the ID is still live before executing by tracking your own instance registry or calling the provider's listing/cleanup API if available"],"exampleFix":"// before\nresult = provider.execute_code(\"sandbox-1\", code, \"python\")  # unknown ID\n\n// after\ninstance_id = provider.create_instance(language=\"python\")\nresult = provider.execute_code(instance_id, code, \"python\")","handlingStrategy":"validation","validationCode":"if instance_id not in getattr(provider, \"_instances\", {}):\n    instance_id = provider.create_instance(language=language)","typeGuard":"def is_known_instance(p, instance_id: str) -> bool:\n    return instance_id in p._instances","tryCatchPattern":"try:\n    result = provider.execute_code(instance_id, code, language)\nexcept RuntimeError as e:\n    if \"Unknown SSH sandbox instance\" in str(e):\n        instance_id = provider.create_instance(language=language)\n        result = provider.execute_code(instance_id, code, language)\n    else:\n        raise","preventionTips":["Treat instance IDs as ephemeral: create, use, destroy within one session","Never persist instance IDs across process restarts — the registry is in-memory","Keep exactly one provider object per SSH host config so IDs cannot cross over"],"tags":["instance-management","ssh","sandbox","state"],"backgroundTag":null,"analyzedSha":"554fb1133ac3861732235ad9c377eb5e0a770665","analyzedAt":"2026-08-15T09:20:16.380Z","schemaVersion":2},"datasetVersion":"2026-08-15T22:17:37.221Z"}