> ## Documentation Index
> Fetch the complete documentation index at: https://e2e.com/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误

> 你可能遇到的所有错误码、所属类别及退出码。

运行器的每个错误都带有类别和错误码。类别决定退出码，错误码说明原因。模型不会选择其中任何一个。`e2e login`、`e2e logout` 和 `e2e models` 是例外，参阅[退出码](#exit-codes)。

```ts title="tests/upgrade.e2e.ts"

test('upgrade to Pro', async ({ agent }) => {
  try {
    await agent.act('upgrade the workspace to Pro');
  } catch (error) {
    if (isAgentError(error) && error.code === 'STEP_TIMEOUT') {
      // the step ran out of time; the message carries the last judgment
      console.error(error.category, error.details);
    }
    throw error;
  }
});
```

## 参考

### 退出码

| 类别 | 退出码 |
| --- | ---: |
| test | 1 |
| configuration | 2 |
| infrastructure | 3 |
| internal | 4 |
| interrupted | 130 |

- 一次运行出现多种错误时，以优先级最高的退出码为准：`130 > 4 > 3 > 2 > 1 > 0`。报告保留每项独立结果。
- 如果测试清理失败（必需的视频未完成保存，或会话未关闭），则使用该清理错误的退出码，通常为 3。
- 准备测试中的断言失败属于测试失败，并会跳过依赖它的测试。准备基础设施缺失则保留其 configuration 或 infrastructure 类别。
- `internal` 类别和退出码 4 保留给违反运行器不变量的情况。目前没有第一方代码抛出该类别的错误码。
- `e2e login`、`e2e logout` 和 `e2e models` 会输出失败消息，不带错误码，并以退出码 1 退出；如果登录或选择器被取消，则以 130 退出。

| 错误码 | 说明 |
| --- | --- |
| [智能体错误码](#agent-codes) | `AgentError` 的 `code` |
| [运行器错误码](#runner-codes) | 输出和报告中的普通字符串 |
| [测试代码错误](#test-code-errors) | 从测试代码中抛出 |

### AgentError

`AgentError` 是由运行器分类的智能体失败，从 `e2e` 导出。

```ts
/** Runner-classified agent failure. */
export class AgentError extends Error {
  /** Closed union, assigned by the runner, never taken from model text. */
  readonly code: AgentErrorCode;
  /** The error class in the table above; it sets the exit code. */
  readonly category: 'test' | 'configuration' | 'infrastructure' | 'internal' | 'interrupted';
  readonly retryable: boolean;
  /** Structured facts: locator, expected, observed, match count, wait time. */
  readonly details: ErrorDetails | undefined;
  /** Sanitized, bounded prose; the same value as `message`. */
  readonly explanation: string;
  /** Artifact path, present only when evidence was captured and permitted. */
  readonly screenshot?: string;
  /** True when this failure reports a blocked step, not a product failure. */
  readonly blocked: boolean;
}
```

<Note>
测试文件在各自的模块域中加载，因此 `instanceof AgentError` 可能为假。请使用 `e2e` 中的 `isAgentError`，并根据 `code` 分支处理，如本页开头的示例所示。
</Note>

#### 智能体错误码

封闭联合类型 `AgentErrorCode` 的成员。`blocked:` 表示受阻判定所报告的障碍类别。

| 错误码 | 触发条件 | 类别 | 退出码 |
| --- | --- | --- | ---: |
| `AUTH_CREDENTIAL_UNAVAILABLE` | `Secret` 或 `credentials.user()` 指定了 `config.credentials` 中不存在的凭据，调用发生在活动运行器之外，或密码提供方未返回至少 6 个字符（码点）的字符串 | configuration | 2 |
| `AUTH_CREDENTIAL_INVALID` | 应用拒绝了已配置的凭据（blocked: credentials） | configuration | 2 |
| `SECRET_UNAVAILABLE` | 运行期间，`Secret` 或 `secrets.get()` 指定了 `config.secrets` 中不存在的机密值，机密值提供方未返回至少 6 个字符（码点）的字符串，或引擎解析了未在其 `secrets` 中声明的机密值。也包括 `host.secret(name)`（`@e2e-dev/core`）指定了未传给 `launch` 的机密值 | configuration | 2 |
| `ENVIRONMENT_UNAVAILABLE` | 被测环境中应用之外的部分宕机或无法访问（blocked: environment） | infrastructure | 3 |
| `SEED_DATA_MISSING` | 步骤依赖的数据在环境中不存在（blocked: seed_data） | configuration | 2 |
| `TEST_SETUP_FAILED` | 未能准备好产品之外的测试前提条件（blocked: test_setup）。也包括违反约定的 `test.extend()` 测试夹具：未调用 `use()` 就返回、调用了两次，或重新定义了测试目标引擎提供的测试夹具 | configuration | 2 |
| `AUTOMATION_UNSUPPORTED` | 步骤需要当前工具集无法执行的交互，例如在设备上右键点击（blocked: automation） | test | 1 |
| `MODEL_UNAVAILABLE` | 未配置模型：内置智能体的 `agents.<name>.model` 不含 AI SDK 模型实例（消息会指出选中的智能体），或 GitHub Copilot 未向该账户提供配置的模型（`model_not_supported`；消息会指出模型）。作为运行级别错误记录一次，然后停止运行。在测试运行中，首次获取 `agent` 测试夹具时会发现模型缺失，首次调用时会发现模型未提供。`e2e explore` 使用内置智能体，因此会在启动任何内容之前检查模型是否缺失，包括自定义执行器的条目。未配置模型的自定义执行器不接受此检查：其 `act` 和 `assert` 步骤会运行，而 `waitFor` 或 `extract` 在首次调用时会因该错误码失败。不会逐出任何[录制](https://e2e.com/docs/zh/cache)。 | configuration | 2 |
| `POLICY_DENIED` | 安全策略拒绝了操作：禁止的目的地、禁止的填入、没有像素时使用 `vision: 'only'`，或读取安全字段。也包括 `app.open` 链接使用了被拒绝的协议方案。[策略拒绝](https://e2e.com/docs/zh/reference/security#policy-denials)列出了所有情况。未知工具，或对声明了字段的内置工具传入未声明的字段，会作为调用结果返回给模型，绝不会作为此错误码返回 | configuration | 2 |
| `APP_UNREACHABLE` | 无法访问应用 URL，或应用命令退出或超过 `startupTimeout`。在 `e2e run` 期间，就绪后的退出只会影响仍有未完成工作的依赖测试目标：中断其活动测试，并跳过排队的测试。诊断信息请参阅[应用命令](https://e2e.com/docs/zh/reference/config#command)。在智能体下，还包括没有更具体错误码的任何引擎故障。在设备上，消息可能指出繁忙或卡死的 iOS 自动化运行器及其恢复方法。参阅[移动端](https://e2e.com/docs/zh/mobile#troubleshooting)。 | infrastructure | 3 |
| `APP_ALREADY_RUNNING` | 在生成测试目标的 `app.command` 进程之前，`readyUrl` 已有响应，且 `reuseExisting` 未生效。停止该进程，或在本地设置 `reuseExisting: true` | infrastructure | 3 |
| `MODEL_PROVIDER_FAILED` | 适配器完成传输重试后，提供方仍出现传输失败（网络错误、5xx、速率限制或 120 秒内无响应）：每次模型调用最多重试 5 次，遵循 `retry-after`，且不超过步骤剩余超时时间。停滞的请求会在 120 秒时中止并重新发送；`agent.act` 步骤的 `--debug` 交互记录会注明这一点。120 秒覆盖整个请求，因此单次回答需要更久的模型也会在此失败。如果提供方的包无法读取错误响应体，则显示 HTTP 状态和响应体，机密值会脱敏，内容截断到 1 KB。也包括提供方以 `error` 结束原因终止的调用，无论附带什么文本，以及 1 分钟内未得到回答的 `e2e doctor --check-model` 调用。不会逐出任何[录制](https://e2e.com/docs/zh/cache) | infrastructure | 3 |
| `CANCELLED` | 运行器在没有进程信号的情况下取消了操作：`e2e mcp` 的 `open_session` 被客户端取消、连接关闭或服务器关闭打断，并已停止它启动的内容；或 `run_tests` 在启动前被取消，或在服务器关闭期间被调用。在 `@e2e-dev/core` 中，也包括被 `signal` 中止的操作，或对已关闭会话的操作 | infrastructure | 3 |
| `MODEL_OUTPUT_INVALID` | 修复预算耗尽后，结构化输出仍未通过校验。在[决策模型](https://e2e.com/docs/zh/decision-models)下：回答没有有效的选项分布、选择了请求未提供的选项，或提供方拒绝了问题。决策不会进行修复 | test | 1 |
| `APP_NOT_OPEN` | 操作需要已打开的应用：尚未运行 `app.open()`，或引擎报告状态无效 | test | 1 |
| `LOCATOR_NOT_FOUND` | 截止时间内没有匹配节点，或智能体操作引用了已不可用的节点。对于经过过滤的定位器，如果失败后的诊断过程能读取过滤链，消息还可能列出每个过滤步骤留下的候选项数量，数量在失败后统计 | test | 1 |
| `LOCATOR_AMBIGUOUS` | 单节点操作匹配了多个节点。立即失败，不进行轮询。对于经过过滤的定位器，如果失败后的诊断过程能读取过滤链，消息可能列出每个过滤步骤留下的候选项数量，数量在失败后统计 | test | 1 |
| `ACTION_FAILED` | 可操作性检查失败、操作超时，或操作可能已经生效。也包括对没有值的节点调用 `inputValue()`，以及对没有选中状态的节点调用 `isChecked()` | test | 1 |
| `STEP_BUDGET_EXHAUSTED` | 得出结论前已耗尽模型调用或操作步骤预算 | test | 1 |
| `STEP_TIMEOUT` | 调用截止时间已到，包括在距离截止时间一个轮询间隔内超时的操作。如果存在最后一次判定，则携带该判定；如果判定无法得出结论，还会附带[视觉提示](https://e2e.com/docs/zh/reference/agent#agent-assert) | test | 1 |
| `CONTEXT_OVERFLOW` | 请求超过了模型的上下文窗口。`act` 会缩短历史记录，如果这使请求变小，就重试一次；判定会立即失败。减小 `agents.<name>.maxObservationBytes`，或将指令拆分为更短的步骤。报告为 blocked: automation | test | 1 |
| `MODEL_REFUSED` | 模型拒绝了请求（结束原因为 `content-filter`），且未返回可用回答。改写指令或使用其他模型。报告为 blocked: automation | test | 1 |
| `ASSERTION_FAILED` | `agent.assert` 判定为假，或定位器、`browser` 或值匹配器失败 | test | 1 |
| `ASSERTION_INCONCLUSIVE` | `agent.assert` 无法判定：屏幕没有显示足以判断真假的信息（相关部分不在屏幕上、仍在加载，或无法读取）。如果模型回答屏幕未显示所需数据，`agent.extract` 会抛出此错误，而不是返回占位符。这始终算作失败，绝不会通过；说明会指出缺失的内容。关闭 `vision`、仅根据语义树判定时，消息可能添加[视觉提示](https://e2e.com/docs/zh/reference/agent#agent-assert) | test | 1 |
| `AUTHENTICATION_FAILED` | 执行器判定应用内登录失败：这是产品判定。`AUTH_CREDENTIAL_INVALID` 是对应的受阻情况，表示应用拒绝了已配置的凭据 | test | 1 |
| `STEP_NO_CONCLUSION` | 执行器耗尽所有轮次，但未调用 `complete_step`。步骤失败，并附带智能体最后的摘要 | test | 1 |
| `REPLAY_STALE` | 启用 `cache.strict` 或 `--strict-cache` 时，步骤的录制存在但已无法回放，因此步骤会直接失败，不调用模型，也不移交给智能体。`step.cache.reason` 为 `invalid-entry`、`wrong-context`、`target-not-found`、`target-ambiguous`、`viewport-changed`、`action-failed`、`action-uncertain`、`end-mismatch` 之一；或者为 `no-entry`，此时缓存目录（不是自定义 `cache.store`）在另一个键下保存着该步骤的录制，消息会指出该键。不会重试：每次尝试都会回放同一份录制。修复时，在不带该标志的读写运行中重新录制，如果配置设置了 `cache.strict`，也要关闭它，然后提交更改后的条目。消息会指出启用严格模式的设置，以及配置的缓存目录（或 `cache.store`） | configuration | 2 |

### 运行器错误码

这些错误码作为普通字符串出现在终端输出和报告中。

| 错误码 | 触发条件 | 类别 | 退出码 |
| --- | --- | --- | ---: |
| `CONFIG_NOT_FOUND` | `--config <path>` 指定的文件不存在，或从工作目录到仓库根目录之间都不存在 `e2e.config.ts`、`e2e.config.mts`、`e2e.config.js` 或 `e2e.config.mjs` | configuration | 2 |
| `CONFIG_AMBIGUOUS` | 同一目录同时存在 `e2e.config.ts` 和 `e2e.config.mts`，或在没有 TypeScript 配置的目录中同时存在 `e2e.config.js` 和 `e2e.config.mjs` | configuration | 2 |
| `CONFIG_LOAD_FAILED` | 配置模块导入失败：包已声明但未安装、包未声明、子路径错误、导出已移除，或求值期间抛出其他异常。消息会指出修复方法。求值期间抛出的配置错误保留自身错误码：配置调用的工厂拒绝选项，或 `secrets.get()` 句柄被转为字符串时，错误码为 `INVALID_CONFIG` | configuration | 2 |
| `INVALID_CONFIG` | 配置模块调用的工厂（`web()`、`mobile()`、`defineEngine()`、`decisionExecutor()`、`decisionFilter()`）拒绝了选项，附带工厂自己的消息。也包括：未知键、超出范围的值、无效枚举或缺少 `targets`；测试目标使用了 `{ name, platform, engine, app, trace, video }` 之外的键；测试目标的 `app` 键未知或格式错误；没有引擎的测试目标设置了 `app`；`web()` 测试目标缺少 `app.url` 或包含设备字段；`mobile()` 测试目标缺少 `app.bundleId` 或 `app.appPath`、包含 `app.url`（尚不支持）、在引擎无法打开链接的测试目标上设置了 `app.linkBase`，或该值不是绝对 URL 或协议方案、含查询或片段、指定了被拒绝的协议方案、在 `bundleId` 中包含链接，或包含未知的权限名称或状态（消息会指出最接近的名称）；`web()` 或 `mobile()` 选项中的未知键，包括 `web({ connect })` 和 `web({ basicAuth })`（消息会指出最接近的键）；`trace` 或 `video` 不是录制模式；已移除的产物类型列表（`artifacts: [...]` 或 `artifacts.kinds`）或 `artifacts.trace` 块（消息会指出它们对应的 `trace` 模式）；已移除的 `artifacts.video` 块或 `video` 产物类型（消息会指出 `video` 选项）；已移除的 `specVersion` 键；引擎选项中的 `secrets.get()` 没有对应的 `secrets` 条目（凭据密码不算）；配置求值时将 `secrets.get()` 引用转为字符串（模板字面量、`String()`），或在需要字符串的位置传入它（`app.command` 的 `args` 条目或 `env` 值；只有声明了机密值的引擎选项才接受它）；`app.command` 的 `args` 条目或 `env` 值不是字符串（值为 `undefined` 的 `env` 条目会被丢弃）；`app.command` 中的未知键（消息会指出最接近的键）；`engine` 不是 `defineEngine` 句柄；`json` 报告器与 `list` 组合，或用于带 `--step` 的运行；重复或格式错误的测试目标名称；机密值或凭据密码少于 6 个字符（码点）；凭据不是 `{ username, password }`、`username` 不是字符串（只有 `password` 可以是函数），或配置与 `E2E_USER_<NAME>_USERNAME` 中都没有用户名；两个凭据或两个机密值的名称映射到同一个 `E2E_USER_*` 或 `E2E_SECRET_*` 覆盖变量（`api-key` 和 `api_key`）；过大的 `agents.<name>.context`；`expect.poll` 的 `timeout` 或 `interval` 不是有限的毫秒数，或在测试外使用值为 0 的 `timeout`；`tests` 值不是 glob 或 glob 列表，或 `tests` 列表仅包含 `!` 排除项；已移除的顶层 `limits` 键；agents 条目为裸 `StepExecutor`（消息会指出 `{ executor }`）或模型实例（消息会指出 `{ model }`）；未知智能体键（消息会指出最接近的键）；已移除的智能体键 `timeout` 和 `maxTurns`（消息会指出 `judgmentTimeout` 和 `maxModelCalls`）；在 `executor` 旁设置 `system` 或 `tools`；`tools` 条目不是由 `defineTool` 构建，或占用了内置工具名称（语法动词、`complete_step`、`locate`、`run_code`、`test_lines`、`start_recording`、`stop_recording` 或 `report_finding`）；`createToolLoopExecutor({ maxTurns })`；应用的 `app.url` 请求空闲端口时设置 `reuseExisting`；端口为 0 的 `app.url` 没有提供服务的 `app.command`；`filters` 值不是 `{ name, filter }` 列表（对于 `decisionFilter` 这样的裸函数，消息会提示调用它）；或过滤器的 `name` 违反测试目标名称规则、超过 256 个字符，或重复使用 | configuration | 2 |
| `CONFIG_NOT_DETERMINISTIC` | 工作进程重新解析配置模块时，得到的摘要与运行器不同 | configuration | 2 |
| `APP_URL_REQUIRED` | 在未声明 `app.url` 的测试目标上导航或使用相对 URL（在没有 `app.linkBase` 的设备测试目标上调用 `app.open(path)`），或 `app.command` 没有可供轮询的 `app.url` 或 `app.readyUrl` | configuration | 2 |
| `INVALID_APP_URL` | 基础 URL 无法解析，或包含用户信息、查询、片段、非 HTTP 协议方案，或在非回环主机上使用明文 HTTP；在非字面回环地址（`127.0.0.1`、`[::1]`）的主机上使用端口 0；或运行无法在回环地址上绑定空闲端口 | configuration | 2 |
| `INVALID_GLOB` | 空模式；除 `tests` 排除项开头的一个 `!` 外，首个路径段仍以 `!` 开头（`!!tests/**`、`./!tests/**`）；单独的 `!`；花括号、字符类或扩展 glob；反斜杠分隔符；绝对路径或 `..` 段；结尾的 `/` 或 `.`；不含通配符却指向目录的 `tests` 条目（消息会指出应填写的 glob）；仅指向项目根目录的模式；或不独占整个路径段的 `**` | configuration | 2 |
| `UNKNOWN_TARGET` | `--target`、`open_session.target` 或 `openHost`（`e2e/runner`）指定了未配置的测试目标 | configuration | 2 |
| `TARGET_REQUIRED` | `e2e mcp` 或 `openHost`（`e2e/runner`）：配置声明了多个测试目标，但没有指定使用哪一个 | configuration | 2 |
| `NO_SESSION` | `e2e mcp`：在 `open_session` 之前或会话结束后调用 `call` 或 `tools`（消息会指出原因），或 `call`、`tools`、`close_session` 指定的 `session` ID 未打开或正在关闭 | configuration | 2 |
| `SESSION_REQUIRED` | `e2e mcp`：多个会话打开时，调用 `call`、`tools` 或 `close_session` 未提供 `session`。消息会列出这些会话 | configuration | 2 |
| `ENGINE_IN_USE` | `e2e mcp`：对某个测试目标调用 `open_session`，但其引擎实例正由另一个打开的会话操作，因为配置从所有会话共享的包中获取该实例。请在配置中，或在配置通过路径导入的文件中创建引擎 | configuration | 2 |
| `ENGINE_NOT_INSTALLED` | `e2e mcp`：`open_session {engine}` 指定的包未安装在项目中、e2e 旁边或 `~/.e2e/engines` 中。消息会给出安装命令 | configuration | 2 |
| `CONFIG_IN_USE` | `e2e mcp`：`open_session` 使用的配置与已打开会话的配置不同，或在通过 `engine` 打开的会话仍打开时使用配置。凭据和机密值在整个进程范围内解析，因此请使用同一配置打开，或先关闭这些会话 | configuration | 2 |
| `SESSION_OPEN` | `e2e mcp`：调用 `open_session` 时，每个会话槽位（`--max-sessions`，默认为 4）都已有打开、正在打开或正在关闭的会话，或服务器正在关闭。请先关闭一个会话 | configuration | 2 |
| `UNKNOWN_TOPIC` | `e2e mcp`：`e2e://guide/{topic}` 资源指定了技能中不存在的主题。消息会列出可用主题 | configuration | 2 |
| `UNKNOWN_TOOL` | `e2e mcp`：`call` 或 `tools` 指定了会话目录中不存在的工具。消息会列出目录。引擎未声明的操作动词则使用 `UNSUPPORTED_CAPABILITY` | configuration | 2 |
| `TEST_AMBIGUOUS` | `e2e mcp`：`open_session` 的 `test` 在会话的测试目标上选中了多个测试。消息会以 `file:line` 列出它们 | configuration | 2 |
| `SESSION_TEST_UNSUPPORTED` | `e2e mcp`：`open_session` 的 `test` 选中了会话无法单独运行的测试：串行组成员、从准备测试的 `session` 开始的测试，或使用多个智能体运行的测试。请使用 `e2e run` 运行它 | configuration | 2 |
| `UNSUPPORTED_ARTIFACT` | 测试目标或将在该目标上运行的测试设置的 [`video` 模式](https://e2e.com/docs/zh/reference/config#recording)要求在某次尝试中录制，但该目标的引擎无法录制视频。消息会指出测试目标；如果模式来自测试，也会指出测试。配置根级别或 `--video` 的模式绝不会触发此错误：它们只适用于能录制的测试目标，并以提示列出其余目标 | configuration | 2 |
| `UNSUPPORTED_CAPABILITY` | 测试目标的引擎未声明某个测试夹具、操作或层级：请求引擎未提供的扩展测试夹具、没有 `locate` 时使用 `screen`、没有 `state` 时恢复状态、没有 `artifacts` 时截图、在持久浏览器上下文上调用 `app.clearState()`（消息会指出模式）、执行器未声明 `vision: true` 时使用 `agent.assert` 的 `vision`，或测试视频正在录制时调用 `app.startRecording()` | configuration | 2 |
| `NO_TESTS` | 可运行的普通测试与测试目标组合数为零。消息会指出原因：没有文件匹配 `tests` glob（会列出相似文件）、位置参数没有匹配项（会指出排除位置参数所指文件的 `!` 条目）、文件未注册测试，或过滤条件排除了全部测试。使用 `--pass-with-no-tests` 可抑制此错误。如果[测试过滤器](https://e2e.com/docs/zh/filters)排除了所有可运行测试，运行会通过（退出码 0）。也适用于 `e2e mcp` 的 `open_session` 中 `test` 未选中任何可运行测试的情况。 | configuration | 2 |
| `RUNNER_BUSY` | 测试套件与另一个测试套件、正在打开或已打开的宿主，或活动尝试重叠；或测试套件运行期间打开宿主；或另一个 `e2e mcp` 的 `run_tests` 正在运行时启动新的调用；或在没有终端时启动 `e2e run --step`，而该目录中已有单步运行，或某次运行在启动时被终止并遗留了锁（消息会指出要删除的文件）。重试前等待测试套件结束并关闭现有宿主；使用 `e2e run --step stop` 结束单步运行，或删除消息指定的锁文件。 | configuration | 2 |
| `RUNNER_NOT_INSTALLED` | 在未安装 `e2e` 的位置调用了 `@e2e-dev/web` 或 `@e2e-dev/mobile` 中的 `test`、`describe` 或钩子，例如仅基于 `@e2e-dev/core` 的程序。同一入口导出的引擎工厂仍然可用。要编写测试，请安装 `e2e` | configuration | 2 |
| `NO_LAST_RUN` | `--last-failed` 在运行写入报告的位置未找到 `report.json`，或该处文件不是 `report-1` 文档。请先不带该标志运行一次。 | configuration | 2 |
| `INVALID_CHANGED_SINCE` | `--changed-since`（`changedSince`）不是字符串、为空或以 `-` 开头。或者，当运行调用测试过滤器或 `e2e explore` 探索变更时，该值在检出的仓库中未指向任何提交，或与 HEAD 没有共同历史记录（浅克隆时消息会提示获取更多历史，否则会说明历史不相关）；或项目不在 git 仓库中、未安装 git，或 git 未在 30 秒内响应 | configuration | 2 |
| `ONLY_IN_CI` | CI 运行中出现了聚焦测试 | configuration | 2 |
| `COLLECTION_ERROR` | 在收集阶段之外注册；标题无效；测试体不是函数；`describe` 的函数体为异步；嵌套串行组；串行组内使用了禁止的选项；`describe` 内包含准备测试；会话名称无效；测试选项格式错误，例如 `tags` 不是不重复名称的列表；测试或 `describe` 使用了调用不接受的选项键（消息会指出最接近的键）；在没有位置参数的运行中，或位置参数选中了该文件时，测试文件导入失败；所选测试使用的会话，或 `e2e explore --session` 指定的会话，没有任何已收集的准备测试生成它（消息会列出声明的会话）；使用会话的测试目标，其引擎没有用于保存会话的 `state` 能力；或位置参数路径在项目根目录之外 | configuration | 2 |
| `SESSION_MISMATCH` | 已存储会话与当前运行、测试目标、引擎、平台或应用标识不匹配。也包括将 `@e2e-dev/core` 的 `SessionState` 传给其他引擎、平台或应用的宿主 | configuration | 2 |
| `SESSION_EXPIRED` | 已存储会话或 `@e2e-dev/core` 的 `SessionState` 在恢复或导入时已过期（configuration，退出码 2），或准备测试保存的状态，其过期时间不晚于创建时间（test，退出码 1） | configuration 或 test | 2 或 1 |
| `SESSION_INVALID` | 已存储会话未通过身份验证，遭到篡改或损坏。也包括 `SessionState.import`（`@e2e-dev/core`）接收到的字节不是 `session-state-1` 文档，或无法用该密钥通过身份验证：密钥不同，或某个字节已更改 | configuration | 2 |
| `SESSION_UNAVAILABLE` | 测试要求的会话没有任何所选准备测试生成 | configuration | 2 |
| `SESSION_CONTRACT` | 准备测试保存同一会话两次、保存了未声明的名称，或结束时未保存某个已声明的会话 | test | 1 |
| `TEST_TIMEOUT` | 尝试超过了解析后的测试 `timeout`。测试体不会被停止：它当前执行的测试执行框架操作会被取消，其测试夹具随尝试结束而失效，因此无法影响下一个测试。如果测试阻塞事件循环，在超时后再经过 `cleanupTimeout`（至少 5 秒），其工作进程会被终止。参阅[钩子](https://e2e.com/docs/zh/reference/test#hooks) | test | 1 |
| `STEP_NOT_AWAITED` | 测试体已结束，但它启动的步骤仍在运行：步骤调用缺少 `await`。该步骤会在调用所在行失败并被取消。如果测试体正常返回，尝试会以此错误码失败；如果测试体抛出异常，尝试保留测试体的错误，并将此错误记录在 `secondaryErrors` 下。如果测试体、`afterEach` 钩子或测试夹具清理已返回，而 `expect.poll` 匹配器仍在运行，该阶段也会以相同方式在调用行失败，匹配器会被取消。由 `beforeAll` 或 `afterAll` 钩子遗留的匹配器会使钩子因 `HOOK_FAILED` 失败 | test | 1 |
| `UNHANDLED_REJECTION` | 没有测试运行时发生 Promise 拒绝。Node 无法确定哪个测试创建了 Promise，因此未处理的拒绝归于它出现时正在运行的测试。如果发生在测试之间，则成为此运行错误，并将该工作进程中最后完成的测试列为可能来源。如果工作进程中尚无测试完成，则会终止工作进程：拒绝成为运行错误，即将执行的测试因 `WORKER_CRASH` 失败。遗留该 Promise 的测试体会像超过 `TEST_TIMEOUT` 的测试体一样继续运行。在 `e2e mcp` 中，会话运行的测试在其代码执行期间也按相同方式归责；测试体结束后，拒绝使用此错误码，由 `close_session` 报告，或在会话关闭后作为警告写入 stderr | test | 1 |
| `HOOK_FAILED` | `beforeAll` 或 `afterAll` 抛出异常。跳过测试套件中的测试。 | test | 1 |
| `UNEXPECTED_PASS` | 标记为 [`test.fail`](https://e2e.com/docs/zh/reference/test#test-fail) 的测试通过了。像其他测试失败一样重试。原因修复后，请移除该标记 | test | 1 |
| `RUN_TIMEOUT` | 运行耗尽了 [`maxDuration`](https://e2e.com/docs/zh/reference/config#maxduration) 或 `--max-duration`。正在运行的测试以 `interrupted` 结束，其余测试以原因 `time-limit` 跳过 | test | 1 |
| `LAUNCH_TIMEOUT` | 引擎初始化或尝试启动超过 `config.launchTimeout` | infrastructure | 3 |
| `CLEANUP_TIMEOUT` | 引擎结束尝试超过 `config.cleanupTimeout`，或尝试结束时，引擎为测试运行的路由或对话框处理函数仍在运行 | infrastructure | 3 |
| `BROWSER_INSTALL_FAILED` | 浏览器准备失败 | infrastructure | 3 |
| `WORKER_INIT_FAILED` | 工作进程始终未就绪 | infrastructure | 3 |
| `WORKER_EXIT` | 工作进程运行文件时意外退出。正在执行的测试因 `WORKER_CRASH` 失败，该文件中的其他测试被跳过。退出前已完成的尝试保留在报告中，包括重试之前的尝试和串行组中已完成的成员。崩溃记录为它们之后的一次尝试；如果发生在最后一次尝试之后（`afterAll` 中），则记录在最后一次尝试上。如果未处理的拒绝导致工作进程结束（参阅 `UNHANDLED_REJECTION`），运行错误是该拒绝，而非此错误 | infrastructure | 3 |
| `WORKER_CRASH` | 工作进程在某个特定测试期间退出 | infrastructure | 3 |
| `WORKER_ENTRY_MISSING` | 无法解析工作进程入口模块。属于打包故障。 | infrastructure | 3 |
| `NODE_UNSUPPORTED` | 运行时无法运行 e2e：Node.js 不在 `^22.22.3 \|\| >=24.8.0` 范围内、Bun 低于 1.4.3，或使用 Deno。CLI 在启动前检查这一点，输出相同消息并以退出码 2 退出。对于不通过 CLI 使用 e2e 运行器的宿主，加载器会在加载配置或测试文件之前再次检查。在 Bun 上，`e2e/runner` 中的 `run`、`list`、`explore` 和 `openHost` 也会抛出此错误：它们需要 Node.js | infrastructure | 3 |
| `TYPESCRIPT_COMPILER_UNAVAILABLE` | 无法加载用于编译 e2e TypeScript 的 oxc；消息会给出原因。最常见的原因是未安装当前平台的原生绑定（`@oxc-transform/binding-<platform>-<arch>`、`@oxc-parser/binding-<platform>-<arch>`）。使用 `--omit=optional` 时，或 `package-lock.json` 在其他平台上生成时（npm/cli#4828），npm 会漏装它们。不带 `--omit=optional` 重新安装，或删除 `package-lock.json` 和 `node_modules` 后运行 `npm install` | infrastructure | 3 |
| `IMAGE_CODEC_UNAVAILABLE` | 无法加载用于读写截图 PNG 的 `@napi-rs/image`；消息会给出原因。它在首次读取或写入截图时加载，因此不截图的运行无需它。最常见的原因是未安装当前平台的原生绑定（`@napi-rs/image-<platform>-<arch>*`）。使用 `--omit=optional` 时，或 `package-lock.json` 在其他平台上生成时（npm/cli#4828），npm 会漏装它。不带 `--omit=optional` 重新安装，或删除 `package-lock.json` 和 `node_modules` 后运行 `npm install`。该包未发布 ppc64、s390x 或 riscv64 上 Linux 的绑定，因此这些平台无法使用 `toHaveScreenshot`，也无法处理运行器需要缩放的智能体截图（任意一边超过 768 px） | infrastructure | 3 |
| `ENGINE_FAILURE` | 没有更具体映射的任何引擎故障 | infrastructure | 3 |
| `WORKER_PROTOCOL` | 工作进程报告了错误的执行单元、尝试与活动尝试重叠、`openHost` 尝试获取另一个宿主持有的引擎实例，或 `host.openSession` 尝试复用已关闭的宿主，或与正在打开、活动或正在关闭的会话重叠。在 `@e2e-dev/core` 中，也包括对另一个宿主持有的引擎实例调用 `launch`，或对已关闭的宿主调用 `host.newSession`，或在已有打开会话时调用它 | infrastructure | 3 |
| `SESSION_KEY_INVALID` | 工作进程收到的会话密钥不是 32 字节。属于打包或 IPC 故障。 | infrastructure | 3 |
| `REPORT_WRITE_FAILED` | 无法写入 `report.json` 或 `ai-trace.json`。记录为运行错误；内存中的结果仍然完整。如果无法写入 `junit.xml`，则改为在 `junit` 报告器的 stderr 上输出一行消息 | infrastructure | 3 |
| `EVALUATE_FAILED` | `browser.evaluate` 在页面中抛出异常，或页面删除或替换了引擎页内代码所需的 JavaScript 内置对象（例如 `Map`），导致后续求值和定位器失败（`@e2e-dev/web`） | test | 1 |
| `INTERRUPTED` | 用户或 CI 信号中止了运行。被 `--max-failures` 或时间限制提前结束的测试也使用此错误码，消息会指出该限制；这种运行的退出码为 1，而非 130 | interrupted | 130 |

#### 测试代码错误

| 错误码 | 触发条件 | 类别 | 退出码 |
| --- | --- | --- | ---: |
| `INVALID_ARGUMENT` | 测试代码中的参数校验拒绝了某个参数 | test | 1 |
| `INVALID_LOCATOR` | 测试代码中的参数校验拒绝了定位器的参数 | test | 1 |
| `ERROR` | 测试代码抛出了无法归入其他错误码的值 | test | 1 |
