Error Codes Reference

Note: The abx commands shown on this page are provided by the Node.js CLI in the cli repository (npm install -g @agent-sandbox/cli). CLI-specific documentation (CLI design, tutorial, reference) lives there too; this repository documents the Python SDK (agent-sandbox) and the container-side runtime (agent-sandbox-server).

All SDK errors inherit from SandboxError and carry code (error code), message, suggestion, and docs_url attributes.

from agent_sandbox.models.errors import SandboxError

try:
    sandbox = await Sandbox.create(template="nonexistent")
except SandboxError as e:
    print(f"[{e.code}] {e.message}")
    print(f"Suggestion: {e.suggestion}")

E1xxx — Authentication Errors (AuthenticationError)

Troubleshooting Steps

1. Run abx config get sandbox_api_key to confirm authentication status
2. Verify environment variables are correctly set
3. Confirm the API Key has not expired or been revoked
4. For E1002, check if the system clock is accurate (date command)

E2xxx — Creation Errors (SandboxCreationError)

Troubleshooting Steps

1. Verify the template name is correct (abx template list)
2. For E2002, check abx list for idle sandboxes
3. For E2004, check template.yaml YAML syntax and field values
4. E2005–E2008 (AI template generation) and the E7xxx build and deploy codes belong to the abx CLI; see the CLI's error-codes reference. The Python SDK no longer defines them

E3xxx — Execution Errors (ExecutionError)

E3004 Details

Note (ADR 2026-09-23): The runtime check_capability() gate has been removed from most modules. CommandsModule, FilesModule, and NetworkModule no longer raise E3004 at call time. Exception: CodeContextModule retains the code capability gate — all its methods (run, create_context, list_contexts, restart_context, remove_context) still raise CapabilityNotSupportedError (E3004) when the code capability is missing (fail-closed). E3004 is also still raised during template resolution / model validation (e.g., resolve_capabilities()).

CapabilityNotSupportedError carries a capability attribute indicating the missing capability name.

try:
    result = await sandbox.run_code("print(1)")
except CapabilityNotSupportedError as e:
    print(f"Missing capability: {e.capability}")  # "code"

Standard capabilities: shell, files, code, terminal, ports

Default capability set: {shell, files, code} (automatically granted when capabilities is not declared)

E4xxx — Filesystem Errors (FileOperationError)

Note: The FileNotFoundError_ class name has a trailing underscore to avoid shadowing Python's built-in FileNotFoundError.

E5xxx — Network Errors (NetworkError)

Note: The ConnectionError_ class name has a trailing underscore to avoid shadowing Python's built-in ConnectionError.

Note: GitHubRateLimitError deliberately shares the E5000 code with NetworkError — it stays a plain network error to callers, while the CLI detects the subtype to offer one-shot interactive github_token onboarding.

E6xxx — Session Errors (SessionError)

E8xxx — Provider Errors (ProviderError)

Raised by the provider layer (Providers guide). All subclass SandboxError. The CLI exit code is the same for every provider.

Missing credential fields of a plugin raise the existing InvalidCredentialsError (E1003, exit 3) and name the provider key and every environment variable that would satisfy it.

Troubleshooting Steps

1. python -m agent_sandbox.providers list (or abx provider list) shows what is installed and which is the default.
2. python -m agent_sandbox.providers doctor <id> checks the manifest, the digest, the handshake and the credentials.
3. For E8011, run provider update <id> or reinstall; do not edit installed files (edit your source and reinstall, or use --link while developing).
4. For E8021, run the plugin command by hand from its directory to see the error; the SDK shows only the last 64 KiB of stderr.

E9xxx — In-sandbox Server API Errors (ServerAPIError)

Raised by ServerClient (Sandbox.server) for responses of the template's SandboxServer. ServerAPIError carries status_code, error_type, error_code (the server's machine code) and endpoint. Existing exception classes are reused where they already fit: HTTP 404 FileNotFoundError becomes FileNotFoundError_ (E4xxx), server TimeoutError becomes CommandTimeoutError, an unreachable server ConnectionError_.

Troubleshooting Steps

1. await sandbox.server.discover() then caps.info("<endpoint>") / caps.denial("<endpoint>") shows why an endpoint is unavailable (disabled, missing scope, path rules).
2. await caps.check_path("files_download_stream", "/some/path", op="read") asks the server for the authoritative path decision without touching the filesystem.
3. For E9001, pass Sandbox.server_at(port, token=...); the token is sent as Authorization: Bearer, the gateway header stays separate.
4. Validate a policy before shipping: agent-sandbox-server check-config --policy server-policy.json --explain files_download_stream --path /home/user/out/a.txt.

Exception Hierarchy

classDiagram
    SandboxError <|-- AuthenticationError
    SandboxError <|-- SandboxCreationError
    SandboxError <|-- ExecutionError
    SandboxError <|-- FileOperationError
    SandboxError <|-- NetworkError
    SandboxError <|-- SessionError
    SandboxError <|-- ProviderError
    ProviderError <|-- ProviderNotFoundError
    ProviderError <|-- ProviderConfigError
    ProviderError <|-- ProviderConflictError
    ProviderError <|-- ProviderFeatureNotSupportedError
    ProviderError <|-- ProviderResourceNotFoundError
    ProviderError <|-- ProviderInstallError
    ProviderError <|-- ProviderIntegrityError
    ProviderError <|-- ProviderTrustError
    ProviderError <|-- ProviderVersionError
    ProviderError <|-- ProviderManifestError
    ProviderError <|-- ProviderProtocolError
    ProviderError <|-- ProviderProcessError
    ProviderError <|-- ProviderTimeoutError
    ProviderError <|-- ProviderMismatchError
    CapabilityNotSupportedError <|-- ProviderFeatureNotSupportedError

    AuthenticationError <|-- InvalidAPIKeyError
    AuthenticationError <|-- TokenExpiredError
    AuthenticationError <|-- InvalidCredentialsError

    SandboxCreationError <|-- TemplateNotFoundError
    SandboxCreationError <|-- QuotaExceededError
    SandboxCreationError <|-- RegionUnavailableError
    SandboxCreationError <|-- TemplateParseError

    ExecutionError <|-- CommandTimeoutError
    ExecutionError <|-- ProcessError
    ExecutionError <|-- CodeExecutionError
    ExecutionError <|-- CapabilityNotSupportedError

    FileOperationError <|-- FileNotFoundError_
    FileOperationError <|-- PermissionDeniedError

    NetworkError <|-- ConnectionError_
    NetworkError <|-- GitHubRateLimitError

    SessionError <|-- SessionNotFoundError
    SessionError <|-- SessionAlreadyExistsError


    class SandboxError { E0000 }
    class AuthenticationError { E1000 }
    class InvalidAPIKeyError { E1001 }
    class TokenExpiredError { E1002 }
    class InvalidCredentialsError { E1003 }
    class SandboxCreationError { E2000 }
    class TemplateNotFoundError { E2001 }
    class QuotaExceededError { E2002 }
    class RegionUnavailableError { E2003 }
    class TemplateParseError { E2004 }
    class SandboxNotFoundError { E2009 }
    class ExecutionError { E3000 }
    class CommandTimeoutError { E3001 }
    class ProcessError { E3002 }
    class CodeExecutionError { E3003 }
    class CapabilityNotSupportedError { E3004 }
    class FileOperationError { E4000 }
    class FileNotFoundError_ { E4001 }
    class PermissionDeniedError { E4002 }
    class NetworkError { E5000 }
    class ConnectionError_ { E5001 }
    class GitHubRateLimitError { E5000 }
    class SessionError { E6000 }
    class SessionNotFoundError { E6001 }
    class SessionAlreadyExistsError { E6002 }
    class ProviderError { E8000 }
    class ProviderNotFoundError { E8001 }
    class ProviderConfigError { E8002 }
    class ProviderConflictError { E8003 }
    class ProviderFeatureNotSupportedError { E8004 }
    class ProviderResourceNotFoundError { E8005 }
    class ProviderInstallError { E8010 }
    class ProviderIntegrityError { E8011 }
    class ProviderTrustError { E8012 }
    class ProviderVersionError { E8013 }
    class ProviderManifestError { E8014 }
    class ProviderProtocolError { E8020 }
    class ProviderProcessError { E8021 }
    class ProviderTimeoutError { E8022 }
    class ProviderMismatchError { E8030 }

Imports

from agent_sandbox.models.errors import (
    SandboxError,
    AuthenticationError,
    InvalidAPIKeyError,
    TokenExpiredError,
    InvalidCredentialsError,
    SandboxCreationError,
    TemplateNotFoundError,
    QuotaExceededError,
    RegionUnavailableError,
    TemplateParseError,
    ExecutionError,
    CommandTimeoutError,
    ProcessError,
    CodeExecutionError,
    CapabilityNotSupportedError,
    FileOperationError,
    FileNotFoundError_,
    PermissionDeniedError,
    NetworkError,
    ConnectionError_,
    GitHubRateLimitError,
    SessionError,
    SessionNotFoundError,
    SessionAlreadyExistsError,
    ProviderError,
    ProviderNotFoundError,
    ProviderConfigError,
    ProviderConflictError,
    ProviderFeatureNotSupportedError,
    ProviderResourceNotFoundError,
    ProviderInstallError,
    ProviderIntegrityError,
    ProviderTrustError,
    ProviderVersionError,
    ProviderManifestError,
    ProviderProtocolError,
    ProviderProcessError,
    ProviderTimeoutError,
    ProviderMismatchError,
)