infiniflow/ragflow · error · SandboxProviderConfigError

SANDBOX_LOCAL_TIMEOUT must be greater than 0.

Error message

SANDBOX_LOCAL_TIMEOUT must be greater than 0.

What it means

Raised by LocalProvider._validate_limits() during initialize() when the configured 'timeout' value is zero or negative. LocalProvider runs agent code as a child process on the host, and a non-positive timeout would make subprocess timeout enforcement meaningless, so initialization fails fast with SandboxProviderConfigError. The value comes from config['timeout'] (default 30) passed to initialize().

Source

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

                "label": "Max Artifacts",
                "description": "Maximum number of files collected from the artifacts directory.",
                "min": 0,
                "max": 100,
            },
            "max_artifact_bytes": {
                "type": "integer",
                "required": False,
                "default": 10485760,
                "label": "Max Artifact Size (bytes)",
                "description": "Maximum size of a single artifact file. Unit: bytes.",
                "min": 1024,
                "max": 104857600,
            },
        }

    def _validate_limits(self) -> None:
        if self.timeout <= 0:
            raise SandboxProviderConfigError("SANDBOX_LOCAL_TIMEOUT must be greater than 0.")
        if self.max_memory_mb <= 0:
            raise SandboxProviderConfigError("SANDBOX_LOCAL_MAX_MEMORY_MB must be greater than 0.")
        if self.max_output_bytes <= 0:
            raise SandboxProviderConfigError("SANDBOX_LOCAL_MAX_OUTPUT_BYTES must be greater than 0.")
        if self.max_artifacts < 0:
            raise SandboxProviderConfigError("SANDBOX_LOCAL_MAX_ARTIFACTS must be greater than or equal to 0.")
        if self.max_artifact_bytes <= 0:
            raise SandboxProviderConfigError("SANDBOX_LOCAL_MAX_ARTIFACT_BYTES must be greater than 0.")

    def _prepare_script(self, instance_dir: Path, language: str, code: str, args_json: str) -> tuple[list[str], Path]:
        if language == "python":
            script_path = instance_dir / "main.py"
            script_path.write_text(build_python_wrapper(code, args_json), encoding="utf-8")
            return [self.python_bin, str(script_path)], script_path
        if language in {"javascript", "nodejs"}:
            script_path = instance_dir / "main.js"
            script_path.write_text(build_javascript_wrapper(code, args_json), encoding="utf-8")
            return [self.node_bin, str(script_path)], script_path

View on GitHub (pinned to 554fb1133a)

Solutions

1. Set 'timeout' to a positive integer number of seconds (e.g. 30) in the LocalProvider config dict passed to initialize().
2. If the value comes from an env var or template, check the rendered config and fix the upstream variable (e.g. SANDBOX_LOCAL_TIMEOUT=30).
3. Omit the 'timeout' key entirely to accept the default of 30 seconds.
4. If you need a per-run timeout, keep initialize() valid and pass the timeout argument to execute_code() instead — it is clamped to the provider maximum anyway.

Example fix

// before
provider = LocalProvider()
provider.initialize({"timeout": 0})

// after
provider = LocalProvider()
provider.initialize({"timeout": 30})

def valid_local_config(config: dict) -> bool:
    return int(config.get("timeout", 30)) > 0

from agent.sandbox.providers.base import SandboxProviderConfigError
try:
    provider.initialize(config)
except SandboxProviderConfigError as e:
    if "SANDBOX_LOCAL_TIMEOUT" in str(e):
        config["timeout"] = 30
        provider.initialize(config)
    else:
        raise

When it happens

Trigger: Calling LocalProvider().initialize({'timeout': 0}) or initialize({'timeout': -5}); also passing a string like '0' which int() coerces to 0. Any config source (env var mapping, YAML, DB-stored provider config) that yields timeout <= 0 triggers this before any instance is created.

Common situations: Misreading 'timeout' as milliseconds and setting e.g. 500 expecting sub-second (still valid) or 0 meaning 'no limit'; a deployment pipeline templating an empty/zero timeout variable into the sandbox config; disabling timeouts by convention (0 = unlimited) which this provider does not support.

Understand the failure class

• Timeouts: ETIMEDOUT, deadlines, and hung requests — what actually expires when a request times out.

Related errors

• SANDBOX_LOCAL_MAX_MEMORY_MB must be greater than 0.
• SANDBOX_LOCAL_MAX_OUTPUT_BYTES must be greater than 0.
• SANDBOX_LOCAL_MAX_ARTIFACTS must be greater than or equal to
• SANDBOX_LOCAL_MAX_ARTIFACT_BYTES must be greater than 0.
• Invalid SSH provider configuration.

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