Error Codes Reference

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. For E2005–E2008 (generation path), follow the Quick Setup printed in the output; pass abx create --template <name> explicitly to skip template generation. For E2008 specifically, add the missing details (or the example description) to the argument, or pass -y to generate from the current description without clarification

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)

E7xxx — Deployment & Build Errors

Deployment Errors (DeployError)

Template Build Errors

Docker/ACR Errors

Exception Hierarchy

classDiagram
    SandboxError <|-- AuthenticationError
    SandboxError <|-- SandboxCreationError
    SandboxError <|-- SandboxNotFoundError
    SandboxError <|-- ExecutionError
    SandboxError <|-- FileOperationError
    SandboxError <|-- NetworkError
    SandboxError <|-- SessionError
    SandboxError <|-- DeployError
    SandboxError <|-- TemplateBuildError
    SandboxError <|-- TemplateBuildTimeoutError
    SandboxError <|-- DockerBuildError
    SandboxError <|-- ACRPushError
    SandboxError <|-- ACRLoginError

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

    SandboxCreationError <|-- TemplateNotFoundError
    SandboxCreationError <|-- QuotaExceededError
    SandboxCreationError <|-- RegionUnavailableError
    SandboxCreationError <|-- TemplateParseError
    SandboxCreationError <|-- QwenCodeNotInstalledError
    SandboxCreationError <|-- QwenCodeCredentialError
    SandboxCreationError <|-- AICodegenError
    SandboxCreationError <|-- DescriptionClarificationError

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

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

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

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

    DeployError <|-- DeployLLMKeyMissingError
    DeployError <|-- DeployAgentError
    DeployError <|-- DeployTimeoutError

    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 QwenCodeNotInstalledError { E2005 }
    class QwenCodeCredentialError { E2006 }
    class AICodegenError { E2007 }
    class DescriptionClarificationError { E2008 }
    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 DeployError { E7000 }
    class DeployLLMKeyMissingError { E7001 }
    class DeployAgentError { E7002 }
    class DeployTimeoutError { E7003 }
    class TemplateBuildError { E7010 }
    class TemplateBuildTimeoutError { E7011 }
    class DockerBuildError { E7020 }
    class ACRPushError { E7021 }
    class ACRLoginError { E7022 }

Related SDK documentation

The Python import paths for these exception classes (from agent_sandbox.models.errors import ...) are listed in the SDK's Error Codes reference in the python-sdk repository.