infiniflow/ragflow · error · RuntimeError

Provider not initialized. Call initialize() first.

Error message

Provider not initialized. Call initialize() first.

What it means

Guard in LocalSandboxProvider.create_instance: initialize() was never successfully completed. initialize() validates limits, creates the 0o700 work_dir, and sets `_initialized` — any earlier failure (e.g., invalid limits raising during _validate_limits) leaves the provider uninitialized.

Source

Thrown at agent/sandbox/providers/local.py:91

    def initialize(self, config: Dict[str, Any]) -> bool:
        self.python_bin = str(config.get("python_bin", "python3"))
        self.node_bin = str(config.get("node_bin", "node"))
        self.work_dir = Path(str(config.get("work_dir", "/tmp/ragflow-codeexec"))).resolve()
        self.timeout = int(config.get("timeout", 30))
        self.max_memory_mb = int(config.get("max_memory_mb", 512))
        self.max_output_bytes = int(config.get("max_output_bytes", 1024 * 1024))
        self.max_artifacts = int(config.get("max_artifacts", 20))
        self.max_artifact_bytes = int(config.get("max_artifact_bytes", 10 * 1024 * 1024))

        self._validate_limits()
        self.work_dir.mkdir(parents=True, exist_ok=True, mode=0o700)
        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)
        instance_id = str(uuid.uuid4())
        instance_dir = self.work_dir / instance_id
        instance_dir.mkdir(mode=0o700)
        (instance_dir / "artifacts").mkdir(mode=0o700)
        self._instances[instance_id] = instance_dir

        return SandboxInstance(
            instance_id=instance_id,
            provider="local",
            status="running",
            metadata={"language": language, "work_dir": str(instance_dir)},
        )

    def execute_code(
        self,
        instance_id: str,

View on GitHub (pinned to 554fb1133a)

Solutions

1. Call initialize(config) and let its exceptions propagate — fix the underlying limit/work_dir error it reports.
2. Verify the configured work_dir parent exists and is writable by the service user.
3. Ensure max_memory_mb / max_output_bytes / max_artifacts / max_artifact_bytes are positive integers.

Example fix

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

# after
provider = LocalSandboxProvider(...)
provider.initialize(config)  # raises on invalid limits or unwritable work_dir
instance = provider.create_instance("python")

import os

work_dir = config.get("work_dir", "/tmp/sandbox")
parent = os.path.dirname(work_dir.rstrip("/")) or "/"
if not os.access(parent, os.W_OK):
    raise ValueError(f"Cannot create sandbox work_dir {work_dir}: parent {parent} not writable")
provider.initialize(config)

def is_local_provider_ready(p) -> bool:
    return bool(getattr(p, "_initialized", False))

try:
    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: Instantiating LocalSandboxProvider and calling create_instance directly; initialize() raised in _validate_limits (bad max_* config values) or work_dir creation failed (permission denied), and the error was swallowed upstream.

Common situations: work_dir path under a directory the process cannot write (read-only volume, root-owned dir); config passing non-integer or non-positive limits; unit tests constructing providers without init.

Related errors

• Provider not initialized. Call initialize() first.
• Provider not initialized. Call initialize() first.
• Provider not initialized. Call initialize() first.
• Provider not initialized. Call initialize() first.
• Azure Blob

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