{"record":{"id":"bb3641e3ab65b3c7","repo":"zylon-ai/private-gpt","slug":"failed-to-start-sandbox-e","errorCode":null,"errorMessage":"Failed to start sandbox: {e}","messagePattern":"Failed to start sandbox: (.+?)","errorType":"exception","errorClass":"RuntimeError","httpStatus":null,"severity":"error","filePath":"private_gpt/components/tabular/pandasai_sandbox.py","lineNumber":168,"sourceCode":"\n    def start(self) -> None:\n        if self._started:\n            return\n\n        logger.debug(\"Starting remote sandbox session for user: %s\", self._user_id)\n\n        try:\n            if self._client is None:\n                raise RuntimeError(\"Sandbox client not configured\")\n            self._temp_dir = Path(\n                tempfile.mkdtemp(prefix=f\"zylon_sandbox_{self._user_id}_\")\n            )\n            self._setup_environment()\n            self._started = True\n            logger.debug(\"Remote sandbox session started successfully\")\n        except Exception as e:\n            logger.error(\"Failed to start remote sandbox: %s\", e)\n            raise RuntimeError(f\"Failed to start sandbox: {e}\") from e\n\n    def stop(self) -> None:\n        if not self._started:\n            return\n\n        logger.debug(\"Stopping remote sandbox session for user: %s\", self._user_id)\n\n        try:\n            if self._client:\n                self._run(self._client.close())\n            if self._temp_dir and self._temp_dir.exists():\n                shutil.rmtree(self._temp_dir, ignore_errors=True)\n        except Exception as e:\n            logger.error(\"Error stopping sandbox: %s\", e)\n        finally:\n            self._started = False\n            self._client = None\n            self._temp_dir = None","sourceCodeStart":150,"sourceCodeEnd":186,"githubUrl":"https://github.com/zylon-ai/private-gpt/blob/4a030776a31a901ad80b1bf4d7faa2c1a367efbb/private_gpt/components/tabular/pandasai_sandbox.py#L150-L186","documentation":"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.","triggerScenarios":"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.","commonSituations":"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.","solutions":["Inspect the chained exception (e.__cause__) — 'Sandbox client not configured', mkdtemp errors, and setup errors each have different fixes.","For client-not-configured: fix adapter construction/DI so a live client is injected.","For mkdtemp failures: check TMPDIR permissions and disk space on the host running private-gpt.","For setup failures: verify connectivity and credentials to the remote sandbox service before start().","Retry start() once if the failure is a transient connection drop to the sandbox provider."],"exampleFix":"# before\nsandbox.start()\n\n# after\ntry:\n    sandbox.start()\nexcept RuntimeError as e:\n    cause = e.__cause__ or e\n    logger.error(\"Sandbox start failed, cause=%r\", cause)\n    raise","handlingStrategy":"try-catch","validationCode":null,"typeGuard":null,"tryCatchPattern":"try:\n    sandbox.start()\nexcept RuntimeError as e:\n    cause = e.__cause__ or e\n    if \"not configured\" in str(cause):\n        fix_client_wiring()  # config error, do not retry\n    else:\n        raise  # surface transport/environment failures","preventionTips":["Health-check the sandbox provider before start()","Always inspect e.__cause__ before deciding to retry","Verify TMPDIR writability in the app container"],"tags":["sandbox","lifecycle","wrapper-exception","startup"],"backgroundTag":null,"analyzedSha":"4a030776a31a901ad80b1bf4d7faa2c1a367efbb","analyzedAt":"2026-08-15T03:51:26.951Z","schemaVersion":2},"datasetVersion":"2026-08-15T17:31:12.345Z"}