infiniflow/ragflow · error · RuntimeError

Provider not initialized. Call initialize() first.

Error message

Provider not initialized. Call initialize() first.

What it means

Raised by SSHProvider.create_instance() when called before initialize() succeeded (self._initialized is False). create_instance immediately opens a real SSH client (self._create_ssh_client()) and SFTP session, which requires host/credentials from initialization; the guard fails fast with RuntimeError instead of attempting a connection with empty config.

Source

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

                "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,
                f"mkdir -p {shlex.quote(posixpath.join(remote_work_dir, 'artifacts'))}",
                timeout=min(self.timeout, 10),
            )
            if exit_code != 0:
                raise RuntimeError(f"Failed to create remote artifacts directory: {stderr or stdout or 'unknown error'}")
        except Exception:
            sftp.close()
            client.close()
            raise

View on GitHub (pinned to 554fb1133a)

Solutions

1. Call initialize(config) with valid SSH parameters and confirm it returns True before create_instance().
2. Treat any initialize() exception as fatal for that provider instance; do not continue to instance creation.
3. Wrap lifecycle in a helper that returns an initialized provider, so call sites cannot get an un-initialized one.
4. If initialize() failed, fix the underlying config/connectivity issue first (see the SSH config/connectivity errors it raises).

Example fix

# before
provider = SSHProvider()
instance = provider.create_instance("python")

# after
provider = SSHProvider()
provider.initialize({"host": h, "username": u, "private_key": k})
instance = provider.create_instance("python")

provider = SSHProvider()
assert provider.initialize(config), "SSH init failed"
instance = provider.create_instance("python")

def is_ready(provider) -> bool:
    """True after successful SSH initialize()."""
    return bool(getattr(provider, "_initialized", False))

try:
    instance = provider.create_instance("python")
except RuntimeError as e:
    if "not initialized" in str(e):
        provider.initialize(config)
        instance = provider.create_instance("python")
    else:
        raise

When it happens

Trigger: Constructing SSHProvider() and calling create_instance('python') without initialize(config); proceeding after an initialize() that raised SandboxProviderConfigError or failed _assert_connectivity(); a retry loop that re-creates the provider object but skips re-init.

Common situations: Integration code assuming the constructor connects; initialize() failure swallowed by broad exception handling; provider instances recreated per request in web handlers without lifecycle management.

Related errors

• Provider not initialized. Call initialize() first.
• Provider not initialized. Call initialize() first.
• Provider not initialized. Call initialize() first.
• Invalid SSH provider configuration.
• Failed to create remote artifacts directory: {stderr or stdo

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