zylon-ai/private-gpt · error · RuntimeError

Sandbox client not configured

Error message

Sandbox client not configured

What it means

Raised inside PandasAISandboxAdapter.start() when the adapter was constructed without a sandbox client (self._client is None). The adapter wraps a remote code-execution sandbox; start() is the lifecycle entry point that creates a temp dir and runs environment setup through that client, so a missing client is a programming/configuration error, not a runtime failure. It is immediately re-wrapped into 'Failed to start sandbox: ...' by the except block at line 168.

Source

Thrown at private_gpt/components/tabular/pandasai_sandbox.py:159

        until the coroutine completes.
        """
        if self._loop is not None and self._loop.is_running():
            return asyncio.run_coroutine_threadsafe(coro, self._loop).result()
        return asyncio.run(coro)

    # ------------------------------------------------------------------
    # Lifecycle
    # ------------------------------------------------------------------

    def start(self) -> None:
        if self._started:
            return

        logger.debug("Starting remote sandbox session for user: %s", self._user_id)

        try:
            if self._client is None:
                raise RuntimeError("Sandbox client not configured")
            self._temp_dir = Path(
                tempfile.mkdtemp(prefix=f"zylon_sandbox_{self._user_id}_")
            )
            self._setup_environment()
            self._started = True
            logger.debug("Remote sandbox session started successfully")
        except Exception as e:
            logger.error("Failed to start remote sandbox: %s", e)
            raise RuntimeError(f"Failed to start sandbox: {e}") from e

    def stop(self) -> None:
        if not self._started:
            return

        logger.debug("Stopping remote sandbox session for user: %s", self._user_id)

        try:
            if self._client:

View on GitHub (pinned to 4a030776a3)

Solutions

1. Check where the adapter is constructed: ensure a live sandbox client (e.g. MicrovmSandbox client) is passed in, not None.
2. If reusing after stop(), construct a fresh adapter/client instead of calling start() on a stopped one.
3. Verify the SandboxComponent configuration actually provisions the remote sandbox in this environment.
4. Fail fast at construction time: raise in __init__ when client is None so the error surfaces at wiring, not at first use.

Example fix

# before
sandbox = PandasAISandboxAdapter(client=None, ...)
sandbox.start()  # RuntimeError: Sandbox client not configured

# after
if client is None:
    raise ValueError("PandasAISandboxAdapter requires a configured sandbox client")
sandbox = PandasAISandboxAdapter(client=client, ...)
sandbox.start()

def can_start(sandbox) -> bool:
    return getattr(sandbox, "_client", None) is not None

# assert can_start(sandbox) before sandbox.start()

When it happens

Trigger: Instantiating PandasAISandboxAdapter with client=None (or default) and then calling start(); constructing the adapter before the sandbox provider is ready; a DI/injection misconfiguration that passes the wrong argument so client ends up None; calling start() again after stop() set _client = None at line 185 (note: _started guard does not cover this case).

Common situations: Component wiring errors where SandboxComponent hands a None client; microvm/sandbox provider not provisioned for the deployment; reuse of a stopped adapter (stop() nulls _client but _started is also False, so a second start() hits the None client).

Related errors

• Names already registered: {existing_names}
• Sandbox provider '{name}' is not registered. Available: {ava
• Failed to start sandbox: {e}
• Client not initialized
• Sandbox not started. Call start() first.

AI-assisted analysis of zylon-ai/private-gpt@4a030776a3 (2026-08-15). Data as JSON: /api/errors/cfe83813b2b7688c. Report an issue: GitHub.