错误码参考

说明： 本页出现的 abx 命令由 cli 仓库中的 Node.js CLI 提供（npm install -g @agent-sandbox/cli）。CLI 专属文档（CLI 设计、教程、参考）也在该仓库；本仓库记录 Python SDK（agent-sandbox）与容器侧运行时（agent-sandbox-server）。

所有 SDK 错误都继承自 SandboxError，携带 code（错误码）、message（消息）、suggestion（建议）、docs_url（文档 URL）属性。

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"建议: {e.suggestion}")

E1xxx — 认证错误（AuthenticationError）

排查步骤

1. 运行 abx config get sandbox_api_key 确认认证状态
2. 检查环境变量是否正确设置
3. 确认 API Key 未过期或被吊销
4. 对于 E1002，检查系统时钟是否准确（date 命令）

E2xxx — 创建错误（SandboxCreationError）

排查步骤

1. 确认模板名称正确（abx template list）
2. 对于 E2002，检查 abx list 是否有大量闲置沙箱
3. 对于 E2004，检查 template.yaml 的 YAML 语法和字段值
4. E2005–E2008（AI 生成模板）和 E7xxx 构建、部署错误码属于 abx CLI，见 CLI 的错误码参考。Python SDK 不再定义它们

E3xxx — 执行错误（ExecutionError）

E3004 详细说明

说明（ADR 2026-09-23）：大多数模块的运行时 check_capability() 门控已移除。CommandsModule、FilesModule、NetworkModule 不再在调用时抛出 E3004。例外：CodeContextModule 保留了 code 能力门控——其所有方法（run、create_context、list_contexts、restart_context、remove_context）在 code 能力缺失时仍会抛出 CapabilityNotSupportedError（E3004，fail-closed）。E3004 也仍在模板解析/模型校验时抛出（如 resolve_capabilities()）。

CapabilityNotSupportedError 携带 capability 属性，指示缺少的能力名。

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

标准能力：shell、files、code、terminal、ports

默认能力集：{shell, files, code}（不声明 capabilities 时自动获得）

E4xxx — 文件系统错误（FileOperationError）

注意：FileNotFoundError_ 类名带下划线后缀，以避免遮蔽 Python 内置 FileNotFoundError。

E5xxx — 网络错误（NetworkError）

注意：ConnectionError_ 类名带下划线后缀，以避免遮蔽 Python 内置 ConnectionError。

注意：GitHubRateLimitError 与 NetworkError 共享 E5000 错误码——对调用方仍是普通网络错误，CLI 通过该子类识别限流并提供一次性交互式 github_token 引导。

E6xxx — 会话错误（SessionError）

E8xxx — 提供方错误（ProviderError）

由提供方层抛出（见提供方指南）。全部继承 SandboxError。无论哪个提供方，CLI 退出码都相同。

插件缺少凭证字段时，抛出已有的 InvalidCredentialsError（E1003，退出码 3），并指出提供方键和所有能满足它的环境变量。

排查步骤

1. python -m agent_sandbox.providers list（或 abx provider list）显示已安装的内容和默认提供方。
2. python -m agent_sandbox.providers doctor <id> 检查清单、摘要、握手和凭证。
3. E8011：运行 provider update <id> 或重新安装；不要直接编辑已安装的文件（改你的源码后重新安装，开发期可用 --link）。
4. E8021：到插件目录里手工运行插件命令查看报错；SDK 只显示 stderr 的最后 64 KiB。

E9xxx — 沙箱内服务端 API 错误（ServerAPIError）

由 ServerClient（Sandbox.server）在处理模板内 SandboxServer 的响应时抛出。 ServerAPIError 带有 status_code、error_type、error_code（服务端的机器可读 code）和 endpoint。 已有异常类在语义吻合时被复用：HTTP 404 FileNotFoundError 映射为 FileNotFoundError_（E4xxx）， 服务端 TimeoutError 映射为 CommandTimeoutError，服务端不可达为 ConnectionError_。

排查步骤

1. 先 await sandbox.server.discover()，再用 caps.info("<endpoint>") / caps.denial("<endpoint>") 查看端点不可用的原因（被禁用、缺少 scope、路径规则）。
2. await caps.check_path("files_download_stream", "/some/path", op="read") 向服务端询问权威的路径判定，不会触碰文件系统。
3. E9001：使用 Sandbox.server_at(port, token=...)；令牌以 Authorization: Bearer 发送，网关头独立传递。
4. 发布前校验策略：agent-sandbox-server check-config --policy server-policy.json --explain files_download_stream --path /home/user/out/a.txt。

异常层级结构

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 }

导入

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,
)