infiniflow/ragflow · critical · SandboxProviderConfigError

Failed to initialize sandbox provider: {provider_type}. Conf

Error message

Failed to initialize sandbox provider: {provider_type}. Config keys: {list(config.keys())}

What it means

Raised during sandbox provider bootstrap in agent/sandbox/client.py. The provider class for the configured type was found, but its initialize(config) returned false — meaning the provider rejected its own configuration. For provider types 'local', 'ssh', 'tenki', and 'ucloud_agent_sandbox' this raises SandboxProviderConfigError; other provider types only log the error and return None, leaving the sandbox unconfigured.

Source

Thrown at agent/sandbox/client.py:105

            "e2b": E2BProvider,
            "local": LocalProvider,
            "ssh": SSHProvider,
            "tenki": TenkiProvider,
            "ucloud_agent_sandbox": UCloudAgentSandboxProvider,
        }

        if provider_type not in provider_classes:
            logger.error(f"Unknown provider type: {provider_type}")
            return

        provider_class = provider_classes[provider_type]
        provider = provider_class()

        # Initialize the provider
        if not provider.initialize(config):
            message = f"Failed to initialize sandbox provider: {provider_type}. Config keys: {list(config.keys())}"
            if provider_type in {"local", "ssh", "tenki", "ucloud_agent_sandbox"}:
                raise SandboxProviderConfigError(message)
            logger.error(message)
            return

        # Set the active provider
        _provider_manager.set_provider(provider_type, provider)
        logger.info(f"Sandbox provider '{provider_type}' initialized successfully")

    except SandboxProviderConfigError:
        raise
    except Exception as e:
        logger.error(f"Failed to load sandbox provider from settings: {e}")
        import traceback

        traceback.print_exc()


def _load_provider_config_from_settings(provider_type: str) -> Dict[str, Any]:
    provider_config_settings = SystemSettingsService.get_by_name(f"sandbox.{provider_type}")

View on GitHub (pinned to 554fb1133a)

Solutions

Open the admin panel sandbox settings and complete/fix the configuration for the selected provider type; check the provider's own initialize() for which keys it validates.
For the ssh provider, verify host, port, user, and key/password are set and the host is reachable.
Check the preceding log output — provider.initialize usually logs the specific reason it returned false.
Switch to the 'local' provider temporarily to isolate provider-config issues from code issues.

Example fix

# before (settings)
sandbox: {provider_type: "ssh", config: {host: ""}}

# after
sandbox: {provider_type: "ssh", config: {host: "10.0.0.5", "port": 22, "user": "runner", "key_path": "/keys/id_rsa"}}

Defensive patterns

Strategy: try-catch

Validate before calling

from agent.sandbox.client import get_provider_manager

pm = get_provider_manager()
if not pm.is_configured():
    raise RuntimeError('Sandbox not configured; fix provider settings before running code components')

Try / catch

try:
    init_sandbox_provider(settings)
except SandboxProviderConfigError as e:
    # surface to admin UI / fail deployment; include config key names from the message
    raise

Prevention

Validate sandbox settings immediately after saving in the admin panel, not at first code execution.
For ssh providers, verify reachability and credentials as part of deployment checks.
Watch logs for 'Failed to initialize sandbox provider' with non-raising provider types — they silently leave the sandbox unconfigured.

When it happens

Trigger: Configuring a local/ssh/tenki/ucloud_agent_sandbox provider with bad settings: missing host/port/credentials for ssh, an unreachable or mis-permissioned working directory for local, invalid tenant/region keys for cloud providers. The message includes the config key names (not values) to aid diagnosis.

Common situations: Admin panel sandbox settings half-configured after switching providers; SSH provider pointing at a host that's down or wrong key path; Docker deployments missing mounts the local provider requires; version upgrades renaming config keys so initialize fails.

Related errors

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