zylon-ai/private-gpt · error · RuntimeError

Failed to start sandbox: {e}

Error message

Failed to start sandbox: {e}

What it means

This is the catch-all wrapper in PandasAISandboxAdapter.start(): any exception raised while starting the remote sandbox (missing client, mkdtemp failure, or an error inside _setup_environment) is logged and re-raised as RuntimeError('Failed to start sandbox: <original>'). The original exception is chained via 'from e', so the root cause is in __cause__. The message text is a template — the interpolated detail identifies which sub-step failed.

Source

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

    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:
                self._run(self._client.close())
            if self._temp_dir and self._temp_dir.exists():
                shutil.rmtree(self._temp_dir, ignore_errors=True)
        except Exception as e:
            logger.error("Error stopping sandbox: %s", e)
        finally:
            self._started = False
            self._client = None
            self._temp_dir = None

View on GitHub (pinned to 4a030776a3)

Solutions

1. Inspect the chained exception (e.__cause__) — 'Sandbox client not configured', mkdtemp errors, and setup errors each have different fixes.
2. For client-not-configured: fix adapter construction/DI so a live client is injected.
3. For mkdtemp failures: check TMPDIR permissions and disk space on the host running private-gpt.
4. For setup failures: verify connectivity and credentials to the remote sandbox service before start().
5. Retry start() once if the failure is a transient connection drop to the sandbox provider.

Example fix

# before
sandbox.start()

# after
try:
    sandbox.start()
except RuntimeError as e:
    cause = e.__cause__ or e
    logger.error("Sandbox start failed, cause=%r", cause)
    raise

try:
    sandbox.start()
except RuntimeError as e:
    cause = e.__cause__ or e
    if "not configured" in str(cause):
        fix_client_wiring()  # config error, do not retry
    else:
        raise  # surface transport/environment failures

When it happens

Trigger: Calling start() when self._client is None; tempfile.mkdtemp failing due to disk/permission issues in the temp dir; _setup_environment raising because the remote sandbox cannot be reached or the setup code errors.

Common situations: Sandbox provider (microvm) down or unreachable; read-only or full /tmp in the app container; IAM/network issues between the app and the remote sandbox service; cold-start race where the client object exists but its backing session is dead.

Related errors

• Sandbox provider '{name}' is not registered. Available: {ava
• Sandbox client not configured
• Client not initialized
• Sandbox not started. Call start() first.
• Code execution failed: {message}

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