infiniflow/ragflow · error · RuntimeError

Unknown SSH sandbox instance: {instance_id}

Error message

Unknown SSH sandbox instance: {instance_id}

What it means

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.

Source

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

        return SandboxInstance(
            instance_id=instance_id,
            provider="ssh",
            status="running",
            metadata={"language": language, "remote_work_dir": remote_work_dir},
        )

    def execute_code(
        self,
        instance_id: str,
        code: str,
        language: str,
        timeout: int = 10,
        arguments: Optional[Dict[str, Any]] = None,
    ) -> ExecutionResult:
        if not self._initialized:
            raise RuntimeError("Provider not initialized. Call initialize() first.")
        if instance_id not in self._instances:
            raise RuntimeError(f"Unknown SSH sandbox instance: {instance_id}")

        normalized_lang = self._normalize_language(language)
        instance = self._instances[instance_id]
        client: paramiko.SSHClient = instance["client"]
        sftp: paramiko.SFTPClient = instance["sftp"]
        remote_work_dir: str = instance["remote_work_dir"]

        args_json = json.dumps(arguments or {}, ensure_ascii=False)
        remote_script_path, command = self._upload_script(
            sftp=sftp,
            remote_work_dir=remote_work_dir,
            language=normalized_lang,
            code=code,
            args_json=args_json,
        )

        requested_timeout = self.timeout if timeout is None else int(timeout)
        if requested_timeout <= 0:

View on GitHub (pinned to 554fb1133a)

Solutions

1. Use the exact instance_id returned by the provider's create-instance call and thread it through to execute_code
2. Re-create the instance (create_instance) if it was destroyed or if the process restarted, since _instances is memory-only
3. Verify the ID is still live before executing by tracking your own instance registry or calling the provider's listing/cleanup API if available

Example fix

// before
result = provider.execute_code("sandbox-1", code, "python")  # unknown ID

// after
instance_id = provider.create_instance(language="python")
result = provider.execute_code(instance_id, code, "python")

if instance_id not in getattr(provider, "_instances", {}):
    instance_id = provider.create_instance(language=language)

def is_known_instance(p, instance_id: str) -> bool:
    return instance_id in p._instances

try:
    result = provider.execute_code(instance_id, code, language)
except RuntimeError as e:
    if "Unknown SSH sandbox instance" in str(e):
        instance_id = provider.create_instance(language=language)
        result = provider.execute_code(instance_id, code, language)
    else:
        raise

When it happens

Trigger: 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.

Common situations: 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.

Related errors

• Invalid SSH provider configuration.
• Provider not initialized. Call initialize() first.
• Failed to create remote artifacts directory: {stderr or stdo
• Execution timeout must be greater than 0 seconds, got {reque
• Unsupported language for SSH provider: {language}

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