文档反馈官招募中，报名立赚积分兑换代金券！> HOT
文档中心>Agent Runtime>故障排查>沙箱启动失败排查

沙箱启动失败排查

最近更新时间：2026-05-22 14:54:22

我的收藏

本页目录：

现象描述

调用 StartSandboxInstance 或执行 agr instance create 后，接口直接返回错误，或者实例状态持续停留在 STARTING、转为 STARTING_FAILED，或在启动后进入 FAILED，均表示本次启动没有稳定完成。
只有实例状态为 RUNNING，才表示沙箱已启动成功。各中间状态含义如下：
STARTING：启动过程仍在进行。
STARTING_FAILED：实例在创建或初始化阶段失败。
FAILED：实例曾经启动成功，但后续运行阶段出现异常。
排查前建议先记录以下信息：
RequestId
ToolId 或 ToolName
InstanceId
实例 Status
实例 StopReason（如果返回）
完整错误码和错误消息
最近一次查询时间
说明：
启动相关接口的实例结构中包含 Status 和 StopReason 字段。部分环境可能额外返回 StatusReason 字段，建议一并记录。

可能原因

启动请求缺少必要参数或参数值不合法，例如未提供 ToolId、ToolName、TemplateId，或 Timeout 格式错误。
目标 Tool 不存在、不可用，或当前调用身份没有操作权限。
当前账号可用实例配额不足，启动请求在接口阶段被拒绝。
启动过程中镜像、网络、挂载、探针或白名单能力校验失败。
启动请求已受理，但实例未能从 STARTING 推进到 RUNNING。

解决思路

先区分故障发生在“启动请求阶段”还是“实例状态推进阶段”，再决定排查路径：
1. 如果 StartSandboxInstance 或 agr instance create 直接失败，优先根据错误码定位参数、Tool、权限或配额问题。
2. 如果启动请求已返回 InstanceId，继续查询实例状态，确认实例最终是进入 RUNNING，还是停留在 STARTING、转为 STARTING_FAILED 或进入 FAILED。
3. CLI 中启动操作使用 agr instance create，查询操作使用 agr instance get 和 agr instance list。如果 CLI 无法满足排查需求，可使用 Cloud API StartSandboxInstance 和 DescribeSandboxInstanceList 作为补充入口。

处理步骤

步骤 1：检查 CLI 和云 API 凭证状态

agr status -o json
输出中 Data.Auth.SecretId.Present 和 Data.Auth.SecretKey.Present 表示云 API 凭证是否已注入。任一字段为 false 时，CLI 无法查询实例状态，需先完成 agr init 或补齐环境变量。

步骤 2：通过 CLI 发起启动，或核对现有启动命令

agr instance create --tool-id <tool-id> --timeout 300 -o json
注意以下差异：
CLI 使用 agr instance create 作为启动入口。
CLI 的 --timeout 是秒级整数；Cloud API 的 Timeout 是 300s、10m、1h 格式的 duration 字符串，两者不要混用。
如果命令直接失败，记录返回中的 Failure.Code、Failure.Message 和命令退出状态。
如果命令成功，记录返回中的 InstanceId，继续执行步骤 3。

步骤 3：查询实例状态，判断启动是否完成

agr instance get <instance-id> -o json
按 Tool 聚合同类问题时，可补充执行：
agr instance list --tool-id <tool-id> -o json
agr instance list --status 支持 STARTING、RUNNING、FAILED、STOPPING、STOPPED 五个筛选值。排查 STARTING_FAILED 时，使用 agr instance get 查询具体实例，或先获取未筛选列表再做本地过滤。
根据查询结果判断下一步：
RUNNING：启动成功，转到验证结果。
STARTING：启动仍在进行，按业务容忍度轮询，避免毫秒级高频查询。
STARTING_FAILED：启动未完成，继续执行步骤 4。
FAILED：实例曾经启动成功但运行阶段异常，继续执行步骤 4。
如果启动时设置了 Timeout，超过该超时仍未进入 RUNNING，可视为异常。未显式设置时，以 Tool 默认超时或系统默认值判断。

步骤 4：对照错误码缩小范围

错误码
含义
处理建议
MissingParameter
ToolId、ToolName、TemplateId 同时缺失，或缺少其他必填参数
补齐请求参数后重试
InvalidParameter
请求格式不合法
检查请求体结构、字段名和字段类型
InvalidParameterValue.Timeout
Timeout 格式错误或超出允许范围
Cloud API 使用 300s、10m、1h；CLI --timeout 使用秒级整数
InvalidParameterValue.NetworkMode
网络模式不合法或与 Tool 配置不匹配
检查实例级网络参数与目标 Tool 配置是否一致
ResourceNotFound.SandboxTool
目标 Tool 不存在
核对 ToolId / ToolName，确认 Tool 已创建
ResourceUnavailable.SandboxTool
目标 Tool 当前不可用
先排查 Tool 状态，再重新启动 Instance
ResourceNotFound.SystemImage
实例级替换镜像未在允许范围内
调整镜像配置，或改用已允许的系统镜像
AuthFailure.UnauthorizedOperation
当前身份没有目标 Tool 的操作权限
检查账号身份和授权范围
LimitExceeded.SandboxInstance
实例配额超限
查询当前运行实例数，停止空闲实例或申请提升配额后重试
FailedOperation.RequestInProgress
相同 ClientToken 的请求仍在处理中
等待已有请求完成后再查结果，不要更换 ClientToken
FailedOperation.DuplicateRequest
相同 ClientToken 的请求已提交过
查询已有 InstanceId 的结果，不要重复创建
InternalError
系统内部错误
保留 RequestId，稍后重试；持续出现时提交工单
FailedOperation.InsufficientBalance（部分场景）
余额不足导致启动被拒
记录 RequestId 和账号余额状态，提交工单确认

步骤 5：必要时回退到 Cloud API 入口，保留原始请求和响应

启动请求示例：
{
  "Action": "StartSandboxInstance",
  "ToolId": "sdt-browser-demo",
  "Timeout": "10m",
  "ClientToken": "sandbox-instance-create-001"
}
查询请求示例：
{
  "Action": "DescribeSandboxInstanceList",
  "InstanceIds": [
    "ins-6f4c9c3e"
  ]
}
如果启动请求已返回 InstanceId 但后续查询结果不是 RUNNING，重点保留查询结果中的 Status、StopReason、UpdateTime 和 RequestId。

验证结果

修复后，完成以下核对：
执行 agr instance get <instance-id> -o json，或调用 DescribeSandboxInstanceList 查询同一 InstanceId。
确认实例状态为 RUNNING。
如果查询结果返回 TimeoutSeconds 和 ExpiresAt，确认有效期与预期一致。
如果通过相同 ClientToken 重试创建，先确认之前的请求没有已成功返回实例。

资源清理

实例状态为 FAILED 时，可执行停止或删除：
agr instance delete <instance-id> -o json
或调用 StopSandboxInstance。
实例状态为 STARTING_FAILED 时，是否需要手动清理取决于系统回收策略。建议先保留 InstanceId、RequestId、Status 和最近一次查询结果，再决定是否继续停止或删除。
如果问题来自配额不足，清理空闲实例后再重试，比重复创建更有效。

提交工单

多次重试后仍无法恢复时，提交工单 并附上以下信息：
RequestId
ToolId 或 ToolName
InstanceId
实例 Status
实例 StopReason
完整错误码和错误消息
启动时间与最近一次查询时间
中国站