> ## Documentation Index
> Fetch the complete documentation index at: https://docs.ppio.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Agent Sandbox errors

> Reference for the exceptions the Agent Sandbox SDK raises, the API status codes behind them, and the CLI messages and exit codes reported by a failed command.

Agent Sandbox reports a failure in three ways: the SDK raises an exception or error class, the API returns a status that the SDK maps to one of those classes, and the CLI prints a message and sets an exit code. This page is the reference for all three.

> [!NOTE]
>
> Install the SDK, or the CLI for `ppio` commands, and set the `PPIO_API_KEY` and `PPIO_DOMAIN` environment variables before running these examples. See [Quickstart](https://docs.ppio.ai/sandbox/quickstart.md) and [Install and authenticate](https://docs.ppio.ai/sandbox/cli/install.md).

## SDK errors

The Python SDK raises these classes from `ppio_sandbox.core.exceptions`, plus `CommandExitException` from `ppio_sandbox.core.sandbox.commands.command_handle`. The Node.js SDK exports the matching classes from `ppio-sandbox`.

**SandboxException** `SandboxError`

The base class for all sandbox errors. **Typical cause:** a sandbox failure that no other class covers, including an API status with a message body. **Retry:** not stated.

**TimeoutException** `TimeoutError`

A timeout occurred. The class covers a sandbox timeout (`unavailable`), a request timeout (`canceled`) and a deadline for a process or watch (`deadline_exceeded`). **Typical cause:** the sandbox reached its timeout, or a request or process exceeded its own. **Retry:** increase the timeout that expired. For a sandbox timeout, pass `timeout` / `timeoutMs` at creation or call `set_timeout()` / `setTimeout()`; for a request timeout, raise `request_timeout` / `requestTimeoutMs`. The error message names the option.

**InvalidArgumentException** `InvalidArgumentError`

An invalid argument was provided. **Typical cause:** a value or option that the SDK rejects. **Retry:** not stated.

**NotEnoughSpaceException** `NotEnoughSpaceError`

There is not enough disk space. **Typical cause:** the sandbox filesystem is full. **Retry:** not stated.

**NotFoundException** `NotFoundError`

A resource was not found. Kept for compatibility; use `FileNotFoundException` or `SandboxNotFoundException`. **Typical cause:** the resource is missing. **Retry:** not stated.

**FileNotFoundException** `FileNotFoundError`

A file or directory is not found inside a sandbox. **Typical cause:** a path that does not exist in the sandbox. **Retry:** not stated.

**SandboxNotFoundException** `SandboxNotFoundError`

A sandbox is not found. **Typical cause:** the sandbox does not exist or is no longer running. Resuming a paused sandbox that was killed or never existed raises it with the message `Paused sandbox <sandbox-id> not found`. Code that catches `NotFoundException` / `NotFoundError` also catches it. **Retry:** not stated.

**AuthenticationException** `AuthenticationError`

Authentication failed. **Typical cause:** a missing or invalid API key; the SDK maps an HTTP 401 response to this class. **Retry:** not stated.

**GitAuthException** `GitAuthError`

Git authentication failed. **Typical cause:** invalid Git credentials for a clone or a push. **Retry:** not stated.

**GitUpstreamException** `GitUpstreamError`

Git upstream tracking is missing. **Typical cause:** a push from a branch without an upstream. **Retry:** not stated.

**TemplateException** `TemplateError`

The template uses an envd version that is not compatible with the SDK. **Typical cause:** a template built with an older envd. **Retry:** not stated.

**RateLimitException** `RateLimitError`

The API rate limit is exceeded. **Typical cause:** too many requests in a short interval. **Retry:** the SDK message says to try again later.

**BuildException** `BuildError`

The template build failed. **Typical cause:** invalid credentials for a private registry; a package install that fails inside `run_cmd()` / `runCmd()`; a start command that exits unexpectedly; a ready command that never succeeds; CPU and memory settings that do not satisfy platform limits, including a request over the tier maximums. **Retry:** not stated.

**FileUploadException** `FileUploadError`

A file upload failed. **Typical cause:** an upload during a template build that did not complete. **Retry:** not stated.

**ImageConfigException** `ImageConfigError`

The registry configuration of a base image cannot be read, and the build was told to stop on that failure (`on_config_failure="raise"`). **Typical cause:** a base image whose registry needs credentials or cannot be reached. **Retry:** not stated.

**CommandExitException** `CommandExitError`

A command exited with a non-zero exit code. It carries `stdout`, `stderr`, `exit_code` (`exitCode` in Node.js) and `error`, so the output can still be inspected after the failure. **Typical cause:** the command run in the sandbox returned a non-zero code. **Retry:** not stated.

> [!WARNING]
>
> In Python, `AuthenticationException` and `BuildException` inherit from `Exception`, not from `SandboxException`. In Node.js, `AuthenticationError` and `BuildError` inherit from `Error`. Catch them separately from the sandbox errors.

## API responses

The SDK maps the status of a failed request to one of the classes above.

**401** `AuthenticationException · AuthenticationError`

Unauthorized. The message reads `401: Unauthorized, please check your credentials.` in Python and `Unauthorized, please check your credentials.` in Node.js.

**402** `SandboxException · SandboxError`

The balance cannot cover a new sandbox. The message reads `402: insufficient balance`. Do not retry; stop the batch and top up the balance.

**429** `RateLimitException · RateLimitError`

Rate limit exceeded. The message says to try again later.

Any other error status raises the default class of the call, with the status and the message from the response: `SandboxException` / `SandboxError` for most calls, `BuildException` / `BuildError` for a template build request.

For a `402` response, handle the error in code so a batch stops cleanly instead of retrying:

```python Python theme={null}
from ppio_sandbox import PPIO, SandboxException

try:
    sandbox = PPIO().sandbox.create()
    sandbox.kill()
except SandboxException as e:
    if "402" in str(e):
        raise SystemExit("Top up your PPIO balance: https://console.ppio.ai/billing")
    raise
```

```javascript Node.js theme={null}
import { PPIO } from 'ppio-sandbox'

try {
  const sandbox = await new PPIO().sandbox.create()
  await sandbox.kill()
} catch (e) {
  if (String(e).includes('402')) throw new Error('Top up your PPIO balance: https://console.ppio.ai/billing')
  throw e
}
```

## CLI messages and exit codes

On failure the CLI prints the message and exits with a non-zero code. Some commands report a specific exit code instead.

| Message or behavior | When it appears | Exit code |
| - | - | - |
| `API key is required` | A command calls the sandbox API without an API key. The message names `PPIO_API_KEY`. | 1 |
| `You must be logged in to use this command. Run ppio-sandbox-cli auth login.` | The command finds no stored login, and neither `PPIO_API_KEY` nor `PPIO_ACCESS_TOKEN` is set. The message names both variables. | 1 |
| `No user config found, run ppio-sandbox-cli auth login to log in first.` | A command needs the login configuration file, and the file is missing | 1 |
| `Not logged in` | `ppio auth info` finds no stored login | 0 |
| `Docker is required to build and push the sandbox template. Please install Docker and try again.` | A template build runs without Docker | 1 |
| `Template name <name> is not valid. Template name can only contain lowercase letters, numbers, dashes and underscores.` | A template build gets a name with other characters | 1 |
| `--cmd requires --ready-cmd so PPIO can wait until the sandbox is ready.` | `ppio template create` gets `--cmd` without `--ready-cmd`. `--ready-cmd` alone is allowed. | 1 |
| `The memory in megabytes must be an even number.` | A template build gets an odd memory value | 1 |
| `Docker push failed` | Pushing the template image fails | 1 |
| `Terminal session was killed by user` | The shell of an interactive terminal session (`ppio sandbox connect`, or `ppio sandbox create` without `-d`) exits with code 130, for example after an interrupt. The CLI then closes the connection. | 0 |
| `Sandbox <sandbox-id> wasn't found` | `ppio sandbox info`, `pause`, `resume` or `network` gets a sandbox ID that does not exist | 1 |
| `Failed to kill sandbox <sandbox-id>: wasn't found` | `ppio sandbox kill` gets a sandbox ID that does not exist | 1 |
| Prints the process ID of the command | `ppio sandbox exec --background` | 0 |
| Streams the output of the remote command | `ppio sandbox exec` | The exit code of the remote command |
| Prints the error | `ppio sandbox exec` cannot start the command, or another error occurs | 1 |


## Related topics

- [PPIO Model API and Agent Sandbox](https://docs.ppio.ai/index.md)
- [How Agent Sandbox billing works](https://docs.ppio.ai/sandbox/billing.md)
- [Agent Sandbox: secure cloud sandboxes for AI agents](https://docs.ppio.ai/sandbox/overview.md)


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.