错误码
198 个错误码:Top 30 给「错误码 → 用户动作」,其余按 45 个命名空间给含义与排查入口。
错误码口径
共 198 个错误码:193 个来自 src/** 的 code: '...' 字面量,5 个来自 wire 边界的 STUDIO_WIRE_ERRORS(两者有重叠,取并集)。
错误码是稳定契约:它出现在客户端分支、日志与排障文档里,改名就是破坏性变更。
wire 边界错误
这 5 个码由控制协议的编解码层产生,status 是建议的 HTTP 状态码;0 表示连接层终止,没有 HTTP 响应。
| 错误码 | status | 含义 | 源码 |
|---|---|---|---|
agentkit/not-found | 404 | Unknown operation | src/contracts/definitions.mjs:13 |
STUDIO_REQUEST_INVALID | 400 | Non-serializable JSON request | src/contracts/definitions.mjs:14 |
STUDIO_RESPONSE_INVALID | 502 | Malformed response envelope | src/contracts/definitions.mjs:15 |
gateway/cancelled | 0 | Caller or owning Host cancelled | src/contracts/definitions.mjs:16 |
agentkit/server-unavailable | 0 | Unclassified domain failure | src/contracts/definitions.mjs:17 |
Top 30:错误码 → 用户动作
按「用户最先撞到」的顺序排列。每一行的动作都是可以立刻执行的,不需要读源码。
| 错误码 | 源码 | 用户动作 |
|---|---|---|
AGENT_NOT_FOUND | src/host/routes/agents.mjs:13 | 确认 Agent 是否已被删除,或在当前工作区重新创建 |
INVALID_AGENT_ID | src/host/routes/agents.mjs:52 | 检查 agentId 是否为空或含非法字符 |
MODEL_CREDENTIAL_MISSING | src/model-service.mjs:71 | 到设置里补该模型 profile 的 API Key |
MODEL_NOT_FOUND | src/model-service.mjs:61 | 刷新模型目录;自建端点检查 OPENAI_BASE_URL |
MODEL_URL_INVALID | src/model-service.mjs:37 | 端点必须是 http(s):// 绝对地址 |
CLOUD_CONFIGURATION_REQUIRED | src/remote/control-client.mjs:439 | 先配置云端凭证与控制面地址 |
CLOUD_EXECUTION_MODE_DENIED | src/host/routes/agents.mjs:118 | 该执行模式被策略拒绝,改申请更低档 |
MCP_NOT_FOUND | src/mcp-probes.mjs:21 | 确认 MCP Server 仍在资源列表里 |
MCP_CONFIGURATION_REQUIRED | src/template-resource-library.mjs:36 | 补齐 MCP 连接配置(命令或 URL) |
SKILL_MANIFEST_MISSING | src/skill-files.mjs:35 | 检查 Skill 包是否含 SKILL.md |
SKILL_DOWNLOAD_URL_MISSING | src/providers/native-skill-service.mjs:285 | 为远程 Skill 提供下载地址 |
SKILL_AUTHORIZATION_EXPIRED | src/providers/native-skill-service.mjs:152 | 重新授权 Skill 来源 |
TEMPLATE_SERVER_CREDENTIAL_MISSING | src/template-catalog-client.mjs:14 | 补专家模板服务凭证 |
TEAM_TEMPLATE_INVALID | src/team-template-audit.mjs:53 | 检查 kind、id、version 与必填文本 |
TEAM_TEMPLATE_ROLE_INVALID | src/team-template-contract.mjs:58 | roles[0].name 必须是 lead,角色名不可重复 |
TEAM_RUNTIME_UNAVAILABLE | src/studio-team-runtime.mjs:105 | 角色运行时只能选 dsh-native 或 harness |
DEPLOYMENT_CREATE_INTERRUPTED | src/studio-deployments.mjs:364 | 先对账云端状态,再决定重试 |
DEPLOYMENT_UPDATE_INTERRUPTED | src/deployment-rollouts.mjs:167 | 同上;不要连续重试更新 |
SESSION_NOT_FOUND | src/host/routes/sessions.mjs:27 | 确认 sessionId 属于当前 Host |
SESSION_ID_INVALID | src/prompt-prediction/host.mjs:196 | sessionId 不能为空 |
BUILD_NOT_READY | src/host-remote.mjs:166 | 等构建进入可用状态再下载 |
RUNTIME_UNSUPPORTED | src/runtime-contract.mjs:67 | runtime.type 不是 STUDIO_RUNTIME_TYPES 里的值时 |
RUN_IDENTITY_INVALID | src/providers/dsh-runtime.mjs:41 | 补全 agentId / sessionId / runId / buildId |
REQUEST_TOO_LARGE | src/model-proxy-handler.mjs:47 | 缩小请求体,或改用分片上传 |
INVALID_QUERY | src/agent-catalog.mjs:9 | 检查查询串的类型与枚举值 |
CREDENTIAL_VALUE_MISSING | src/host/routes/credentials.mjs:7 | 填写该凭证引用的值 |
EVALUATION_TARGET_NOT_FOUND | src/host/services/automation.mjs:47 | 先登记评测目标 |
CHANNEL_URL_INVALID | src/channel-connector.mjs:8 | 渠道地址必须是 HTTPS 绝对地址 |
STUDIO_HOST_INCOMPATIBLE | src/host/compatibility.mjs:40 | 升级 DSH 基座到 studio.plugin.json 要求的版本 |
DSH_PLUGIN_INDEX_UNAVAILABLE | src/dsh-plugin-index.mjs:58 | 检查索引地址可达性;失败时市场保留上一次结果 |
命名空间索引
其余 170 个码按命名空间分组,每组的含义与首个排查入口如下。
| 命名空间 | 条数 | 含义 | 排查入口 |
|---|---|---|---|
STUDIO | 25 | Studio 宿主与路由。 | src/agent-preset-admission.mjs:162 |
NATIVE | 16 | 原生引擎、A2A 与 Web 授权。 | src/agent-preset-admission.mjs:337 |
CLOUD | 15 | 云端执行模式与流式响应。 | src/cloud-execution-modes.mjs:41 |
CODEX | 11 | Codex App Server 与插件市场。 | src/client/dsh/codex-tool.mjs:33 |
SKILL | 10 | Skill 下载、授权与运行。 | src/providers/native-skill-connection.mjs:92 |
INVALID | 8 | 入参校验。 | src/agent-catalog.mjs:9 |
MANAGED | 8 | 托管运行时、资源与输入冲突。 | src/host/bootstrap.mjs:158 |
MODEL | 8 | 模型目录、端点与凭证。 | src/model-endpoint.mjs:9 |
DSH | 7 | DSH 基座与插件索引。 | src/agent-preset-admission.mjs:345 |
RUNTIME | 7 | 运行时路由与传输。 | src/cloud-runtime-fetch.mjs:6 |
MCP | 6 | MCP Server 绑定与配置。 | src/host/services/resource-tools.mjs:21 |
RESOURCE | 5 | 资源目录与适配器。 | src/host/services/optional-resource.mjs:10 |
SESSION | 5 | 会话标识与导出。 | src/host/routes/sessions.mjs:19 |
TEMPLATE | 5 | 专家模板服务。 | src/template-catalog-client.mjs:14 |
AUTOMATION | 4 | 自动化运行与投递。 | src/native-automation-runner.mjs:21 |
CHANNEL | 4 | 渠道连接与轮次。 | src/channel-connector.mjs:8 |
HOST | 4 | Host 连接与工具调用。 | src/providers/dsh-runtime-plugin.mjs:167 |
RESPONSES | 4 | Responses 协议投影。 | src/frozen-build-runtime.mjs:88 |
TEAM | 4 | 专家团角色与模板。 | src/providers/codex-resource-context.mjs:18 |
AGENTKIT | 3 | 未归入命名空间的独立错误码。 | src/contracts/definitions.mjs:17 |
BUILTIN | 3 | 内置 Skill 清单。 | src/builtin-skills.mjs:44 |
UPSTREAM | 3 | 上游流式传输。 | src/model-proxy-handler.mjs:150 |
A2A | 2 | Agent-to-Agent 控制面。 | src/providers/native-a2a-receipt.mjs:97 |
AGENT | 2 | Agent 目录与修订版本解析。 | src/host/routes/agents.mjs:13 |
BUILD | 2 | 构建与冻结运行时。 | src/agent-preset-admission.mjs:327 |
CREDENTIAL | 2 | 凭证引用与取值。 | src/host/routes/credentials.mjs:6 |
DEPLOYMENT | 2 | 部署中断与恢复。 | src/deployment-rollouts.mjs:167 |
DISCOVERY | 2 | MCP / Skill 发现。 | src/dsh-plugin-discovery.mjs:244 |
EVALUATION | 2 | 评测目标与执行。 | src/host/routes/evaluations.mjs:8 |
REQUEST | 2 | 请求体与取消。 | src/model-proxy-handler.mjs:47 |
RUN | 2 | 运行标识。 | src/providers/dsh-runtime.mjs:41 |
STAR | 2 | 本机 Star Harness 的安装、版本与工作区绑定。 | src/host/routes/http.mjs:65 |
BOUND | 1 | 资源绑定解析。 | src/providers/codex-resource-context.mjs:137 |
CHANNELS | 1 | 渠道子系统可用性。 | src/host/routes/channels.mjs:8 |
GATEWAY | 1 | 未归入命名空间的独立错误码。 | src/host/routes/dispatcher.mjs:28 |
LOCAL | 1 | 本地 Harness 生命周期。 | src/host/routes/http.mjs:24 |
MEMORY | 1 | 记忆库写入结果。 | src/providers/native-cloud-memory-turn.mjs:113 |
OBSERVABILITY | 1 | 可观测性导出。 | src/host/routes/traces.mjs:9 |
SCHEDULE | 1 | 计划任务。 | src/host/services/automation.mjs:29 |
SCHEDULER | 1 | Host 调度器。 | src/host/routes/schedules.mjs:14 |
SERVER | 1 | 服务端连接。 | src/remote/compatibility-methods.mjs:57 |
STATELESS | 1 | 无状态调用入参。 | src/model-proxy-handler.mjs:55 |
SUMMON | 1 | 模板召唤冲突。 | src/template-summon.mjs:108 |
TOOL | 1 | 工具查找。 | src/providers/dsh-presentation-tools.mjs:7 |
USER | 1 | 用户提问校验。 | src/providers/user-question-tool.mjs:54 |
完整清单
按命名空间列出全部错误码。复制某个码到仓库里搜索,就能定位抛错点。
STUDIO (25) — STUDIO_AGENT_REQUIRED · STUDIO_BUILD_ENGINE_UNSUPPORTED · STUDIO_DEPLOYMENT_REQUIRED · STUDIO_DSH_A2A_UNAVAILABLE · STUDIO_HOST_INCOMPATIBLE · STUDIO_IMAGE_ATTACHMENT_UNAVAILABLE · STUDIO_INPUT_REQUIRED · STUDIO_LEGACY_HARNESS_RETIRED · STUDIO_NATIVE_AGENT_POLICY_INVALID · STUDIO_NATIVE_AGENT_POLICY_UNAVAILABLE · STUDIO_NATIVE_APPROVAL_DECISION_INVALID · STUDIO_NATIVE_BUILTIN_UNAVAILABLE · STUDIO_NATIVE_EXACT_NUMBER_UNSUPPORTED · STUDIO_NATIVE_MCP_SCHEMA_ENGINE_REQUIRED · STUDIO_NATIVE_PRESENTATION_UNAVAILABLE · STUDIO_NATIVE_TURN_REQUIRED · STUDIO_PRESET_AGENT_ID_MISSING · STUDIO_PRESET_REGISTRY_RETIRED · STUDIO_PRESET_RESOURCES_UNAVAILABLE · STUDIO_PRESET_RUNTIME_UNSUPPORTED · STUDIO_PRESET_SCOPE_CLOSED · STUDIO_REQUEST_INVALID · STUDIO_RESPONSE_INVALID · STUDIO_ROUTE_MISSING · STUDIO_SCOPE_DISPOSED
NATIVE (16) — NATIVE_A2A_ASSERT_CURRENT_REQUIRED · NATIVE_A2A_AUTHORIZE_REQUIRED · NATIVE_A2A_BINDING_DESCRIPTION_REQUIRED · NATIVE_A2A_DISCOVERY_REQUIRED · NATIVE_A2A_EXPOSURE_PLAN_REQUIRED · NATIVE_A2A_SCOPE_REQUIRED · NATIVE_ENGINE_CONFIG_INVALID · NATIVE_ENGINE_MODEL_UNAVAILABLE · NATIVE_ENGINE_TOOL_EFFECT_UNAVAILABLE · NATIVE_ENGINE_TOOL_POLICY_UNAVAILABLE · NATIVE_ENGINE_TOOLS_CLOSED · NATIVE_ENGINE_UNAVAILABLE · NATIVE_ENGINE_VERIFICATION_UNAVAILABLE · NATIVE_ENGINE_WORKSPACE_UNAVAILABLE · NATIVE_EXECUTION_NOT_COMPLETED · NATIVE_WEB_AUTHORIZE_REQUIRED
CLOUD (15) — CLOUD_AGENT_DELETED · CLOUD_AGENT_ID_INVALID · CLOUD_CONFIGURATION_REQUIRED · CLOUD_DELETE_UNAVAILABLE · CLOUD_EXECUTION_MODE_DENIED · CLOUD_EXECUTION_MODE_INVALID · CLOUD_EXECUTION_MODE_UNAVAILABLE · CLOUD_EXECUTION_MODE_UNSUPPORTED · CLOUD_IMAGE_INPUT_UNAVAILABLE · CLOUD_RUN_CANCELLED · CLOUD_RUN_FAILED · CLOUD_STREAM_INCOMPLETE · CLOUD_STREAM_INVALID · CLOUD_STREAM_ITEM_CHANGED · CLOUD_SUBACCOUNT_REQUIRED
CODEX (11) — CODEX_AGENT_REQUIRED · CODEX_MARKETPLACE_PARTIAL · CODEX_MODEL_PROVIDER_UNAVAILABLE · CODEX_PLUGIN_DETAILS_INVALID · CODEX_PLUGIN_INVENTORY_UNAVAILABLE · CODEX_PLUGIN_MARKETPLACE_MISSING · CODEX_PLUGIN_METADATA_UNAVAILABLE · CODEX_PLUGIN_NOT_FOUND · CODEX_TOOL_CONVERSION_FAILED · CODEX_TOOL_OUTCOME_UNKNOWN · CODEX_WORKSPACE_UNAVAILABLE
SKILL (10) — SKILL_AUTHORIZATION_EXPIRED · SKILL_BINDING_INVALID · SKILL_DOWNLOAD_INVALID · SKILL_DOWNLOAD_URL_INVALID · SKILL_DOWNLOAD_URL_MISSING · SKILL_LOAD_AUTHORITY_CHANGED · SKILL_MANIFEST_MISSING · SKILL_PAGE_BUDGET_INVALID · SKILL_RUNTIME_DEADLINE · SKILL_SERVICE_INVALID_RESPONSE
INVALID (8) — INVALID_AGENT_ID · INVALID_CONVERSATION_INPUT · INVALID_FEEDBACK · INVALID_JSON · INVALID_QUERY · INVALID_RESOURCE_CURSOR · INVALID_RESOURCE_SOURCE · INVALID_SESSION_ID
MANAGED (8) — MANAGED_HARNESS_RUN_INCOMPLETE · MANAGED_HOST_INPUT_CONFLICT · MANAGED_RESOURCE_IDENTITY_UNAVAILABLE · MANAGED_RESOURCE_INVALID · MANAGED_RESOURCE_PERMIT_REQUIRED · MANAGED_RUNTIME_DELETE_UNCONFIRMED · MANAGED_RUNTIME_MODEL_INVALID · MANAGED_RUNTIME_REQUIRED
MODEL (8) — MODEL_CATALOG_FAILED · MODEL_CREDENTIAL_MISSING · MODEL_ENDPOINT_INVALID · MODEL_NOT_FOUND · MODEL_PROFILE_EXISTS · MODEL_PROFILE_INVALID · MODEL_UPSTREAM_ERROR · MODEL_URL_INVALID
DSH (7) — DSH_PLUGIN_INDEX_TIMEOUT · DSH_PLUGIN_INDEX_UNAVAILABLE · DSH_PLUGIN_INDEX_URL_REJECTED · DSH_PRESET_COMPOSITION_UNAVAILABLE · DSH_PRESET_REGISTRY_UNAVAILABLE · DSH_PRESET_ROUTE_UNAVAILABLE · DSH_TURN_FAILED
RUNTIME (7) — RUNTIME_HOST_CAPABILITY_UNAVAILABLE · RUNTIME_MODEL_UNAVAILABLE · RUNTIME_REQUEST_CONFLICT · RUNTIME_REQUEST_HISTORY_UNAVAILABLE · RUNTIME_REQUEST_METADATA_UNAVAILABLE · RUNTIME_TRANSPORT_CLOSED · RUNTIME_UNSUPPORTED
MCP (6) — MCP_BINDING_AMBIGUOUS · MCP_CONFIGURATION_REQUIRED · MCP_ID_INVALID · MCP_NOT_FOUND · MCP_RESOURCE_ADAPTER_MISSING · MCP_RESOURCE_NOT_BOUND
RESOURCE (5) — RESOURCE_ADAPTER_MISSING · RESOURCE_CATALOG_INVALID_RESPONSE · RESOURCE_CATALOG_TOO_LARGE · RESOURCE_OVERVIEW_TRUNCATED · RESOURCE_SERVICE_UNAVAILABLE
SESSION (5) — SESSION_EXPORT_TOO_LARGE · SESSION_EXPORT_UNAVAILABLE · SESSION_ID_INVALID · SESSION_ID_MISSING · SESSION_NOT_FOUND
TEMPLATE (5) — TEMPLATE_CANCELLED · TEMPLATE_INTERRUPTED · TEMPLATE_SERVER_CREDENTIAL_MISSING · TEMPLATE_SERVER_REJECTED · TEMPLATE_SERVICE_CLOSED
AUTOMATION (4) — AUTOMATION_OUTCOME_UNKNOWN · AUTOMATION_SERVICE_UNAVAILABLE · AUTOMATION_SESSION_NOT_DURABLE · AUTOMATION_TIMEOUT
CHANNEL (4) — CHANNEL_AGENT_UNAVAILABLE · CHANNEL_REQUEST_NOT_FOUND · CHANNEL_TURN_INCOMPLETE · CHANNEL_URL_INVALID
HOST (4) — HOST_CONNECTION_MISSING · HOST_TOOL_OUTCOME_UNAVAILABLE · HOST_TOOL_REJECTED · HOST_TOOL_RUN_MISMATCH
RESPONSES (4) — RESPONSES_FROZEN_MODEL_MISMATCH · RESPONSES_PREVIOUS_NOT_COMPLETED · RESPONSES_PREVIOUS_NOT_FOUND · RESPONSES_PROJECTION_NOT_JSON
TEAM (4) — TEAM_PRESET_CONFLICT · TEAM_ROLE_UNAVAILABLE · TEAM_RUNTIME_UNAVAILABLE · TEAM_TEMPLATE_NONE
AGENTKIT (3) — agentkit/bad-request · agentkit/not-found · agentkit/server-unavailable
BUILTIN (3) — BUILTIN_META_TOOL_FORBIDDEN · BUILTIN_SKILL_MANIFEST_EMPTY · BUILTIN_SKILL_MANIFEST_MISSING
UPSTREAM (3) — UPSTREAM_EVENT_TOO_LARGE · UPSTREAM_STREAM_ERROR · UPSTREAM_STREAM_TRUNCATED
A2A (2) — A2A_QUESTION_STALE · A2A_TOOL_ACTIVITY_UNAVAILABLE
AGENT (2) — AGENT_NOT_FOUND · AGENT_REVISION_INVALID
BUILD (2) — BUILD_NOT_READY · BUILD_RUNTIME_UNSUPPORTED
CREDENTIAL (2) — CREDENTIAL_NAME_INVALID · CREDENTIAL_VALUE_MISSING
DEPLOYMENT (2) — DEPLOYMENT_CREATE_INTERRUPTED · DEPLOYMENT_UPDATE_INTERRUPTED
DISCOVERY (2) — DISCOVERY_TIMEOUT · DISCOVERY_UNAVAILABLE
EVALUATION (2) — EVALUATION_TARGET_NOT_FOUND · EVALUATION_UNAVAILABLE
REQUEST (2) — REQUEST_CANCELLED · REQUEST_TOO_LARGE
RUN (2) — RUN_IDENTITY_INVALID · RUN_IDENTITY_MISMATCH
STAR (2) — STAR_HARNESS_OWNER_REQUIRED · STAR_HARNESS_UNSUPPORTED
BOUND (1) — BOUND_TOOL_NOT_FOUND
CHANNELS (1) — CHANNELS_UNAVAILABLE
GATEWAY (1) — gateway/cancelled
LOCAL (1) — LOCAL_HARNESS_RETIRED
MEMORY (1) — MEMORY_OUTCOME_UNKNOWN
OBSERVABILITY (1) — OBSERVABILITY_UNAVAILABLE
SCHEDULE (1) — SCHEDULE_AGENT_NOT_LOCAL
SCHEDULER (1) — SCHEDULER_UNAVAILABLE
SERVER (1) — SERVER_CONNECTION_MISSING
STATELESS (1) — STATELESS_INPUT_REQUIRED
SUMMON (1) — SUMMON_REQUEST_CONFLICT
TOOL (1) — TOOL_NOT_FOUND
USER (1) — USER_QUESTION_INVALID
版本与兼容性
| 项 | 值 | 说明 |
|---|---|---|
| 错误码总数 | 198 | 新增只增不改;改名要留别名 |
| wire 码 | 5 | src/contracts/definitions.mjs |
| 命名空间 | 45 | 首段下划线前缀 |
| 非错误码排除 | ENOTFOUND · UNKNOWN · CLOUD | Node errno / A2A 信封 / 工具标签,不是 Studio 错误码 |
开发者入口
| 内容 | 源码位置 |
|---|---|
| wire 错误定义 | src/contracts/definitions.mjs |
| 运行时错误码 | src/runtime-contract.mjs |
| 模板错误码 | src/team-template-contract.mjs |
| 目录错误码 | src/dsh-plugin-catalog.mjs |
| 排障页 | content/docs/help/troubleshooting.mdx |
相关测试:
| 测试文件 | 位置 |
|---|---|
| desktop-module-graph.test.mjs | tests/desktop-module-graph.test.mjs |
| studio-wire-contracts.test.mjs | tests/studio-wire-contracts.test.mjs |