> ## Documentation Index
> Fetch the complete documentation index at: https://opencompass-docs-preview-pr-354.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 错误处理

AgentCompass 把任务 attempt 中每个未解决的问题记录为带严重级别的 issue。严重级别决定 runtime 是否重试、任务是否保留有效分数，以及整次运行是否成功。本页集中说明这些规则；重试参数本身在[运行控制](/zh/user_guide/using_agentcompass/run_controls#只重试瞬时失败)中设置。

| 想了解什么 | 查看哪里 |
| - | - |
| issue 包含哪些信息 | [读懂 issue](#读懂-issue) |
| 失败为什么是 FATAL、ERROR 或 WARNING | [失败如何分级](#失败如何分级) |
| 哪些失败会重试，重试会重复什么 | [重试失败的工作](#重试失败的工作) |
| 失败的任务是否仍有分数 | [失败对分数的影响](#失败对分数的影响) |
| 运行为什么没有正式分数或以非零状态退出 | [运行失败时](#运行失败时) |
| `--reuse` 如何处理失败的任务 | [失败后的复用](#失败后的复用) |

## 读懂 issue

[任务结果](/zh/user_guide/other_features/results/task_results#attempt-级字段)中的每个 attempt 都保存 `issues` 列表；没有未解决的问题时为 `[]`：

```json theme={"system"}
{"severity": "fatal", "phase": "evaluate", "code": "judge_failed", "message": "HTTP 503: ..."}
```

| 字段 | 含义 |
| - | - |
| `severity` | `fatal`、`error` 或 `warning`。 |
| `phase` | 问题发生的阶段：`setup`、`run`、`collect`、`evaluate` 或 `cleanup`。 |
| `code` | 稳定标识，例如 `judge_failed`、`model_timeout` 或 `environment_failed`，可被重试模式匹配。 |
| `message` | 单行摘要，已脱敏可识别的凭证。 |

完整的 traceback 和异常链保存在同一 attempt 的 `artifacts.execution_diagnostics` 中。issue 与分数相互独立：带有 ERROR 或 WARNING 的 attempt 仍可能包含有效的 Benchmark 指标。

attempt 的 `status` 由其 FATAL 和 ERROR issue 所在的阶段推导：位于 `setup`、`run` 或 `collect` 时为 `run_error`，位于 `evaluate` 时为 `eval_error`，两者都有时为 `run_error_or_eval_error`。只有 WARNING 的 attempt 保持 `completed`。用 `status` 判断 attempt 在哪里失败，用 `severity` 判断失败有多严重。

## 失败如何分级

各组件在失败实际发生的位置分级，因此同一种异常在不同位置可能有不同的严重级别。

| 严重级别 | 含义 | 常见原因 |
| - | - | - |
| FATAL | 评测基础设施或必需的服务失败，结果不能反映 agent 的能力。 | setup 失败；Environment 创建、命令执行、文件传输或网络策略切换失败；搜索等外部工具服务失败；模型鉴权、配额或服务端错误（HTTP 401、402、403、429 或 5xx）；Judge 请求失败，或 Judge 输出不符合约定格式；Harness 发生超时以外的崩溃。 |
| ERROR | agent 没有正常结束，但其输出仍可能被评分。 | 模型或 Harness 超时；没有有效的模型输出；Harness 达到轮次或步数上限；Benchmark 自身推理循环或评分代码中的意外异常。 |
| WARNING | 仅用于诊断，不影响重试和分数有效性。 | 验证器奖励缺失或无法解析，以及缺少必需的交付物，两者都按失败或 `0` 计分；诊断副本写入失败；Environment 清理失败。 |

各 Benchmark 或 Harness 特有的分级见对应的组件页面，例如哪些 Judge 响应视为无效。

### Judge 与验证器

依赖 LLM Judge 评分的 Benchmark 在 Judge 失败时无法得到有效观测。Judge 请求失败，或响应不符合约定的输出格式（例如 JSON 无效或缺少评分字段）时记为 FATAL，而不是判为答错。

Benchmark 自有的验证器（例如测试脚本）则不同。奖励缺失或无法解析时，任务按失败或 `0` 计分，并记录 WARNING。可确认的受信验证环境准备失败（例如无法准备评测 Environment）仍为 FATAL。

### 超时与上限

Harness 接收 agent 执行预算，并把自身超时报告为 ERROR。如果 Harness 在该预算加 [`run_timer_compensation_seconds`](/zh/user_guide/using_agentcompass/timeouts#给-harness-留出超时收尾时间) 内仍未停止，runtime 会终止它并记录 ERROR `run_failed`。被终止的 Harness 未写完的占位文件不会额外产生 FATAL。

Harness 因轮次或步数上限结束时记录 ERROR `harness_max_iterations`；无法确认上限类型时记录 `harness_limit_reached`。无论超时还是达到上限，AgentCompass 都会继续收集输出并评分。

`evaluation_timeout_seconds` 到期时，runtime 记录 ERROR。部分 Benchmark 为这种情况声明了失败分值，使任务计为失败，而不是缺少观测：

| Benchmark | 评测超时时记录的值 |
| - | - |
| [Terminal-Bench 2](/zh/user_guide/modules/benchmarks/terminal_bench_2)、[2.1](/zh/user_guide/modules/benchmarks/terminal_bench_2_1) 和 [Verified](/zh/user_guide/modules/benchmarks/terminal_bench_2_verified) | `correct=false` |
| [SWE-bench Verified](/zh/user_guide/modules/benchmarks/swebench_verified)、[Multilingual](/zh/user_guide/modules/benchmarks/swebench_multilingual)、[Pro](/zh/user_guide/modules/benchmarks/swebench_pro) 和 [Pro Verified](/zh/user_guide/modules/benchmarks/swebench_pro_verified) | `correct=false` |
| [DeepSWE](/zh/user_guide/modules/benchmarks/deepswe) | `correct=false`、`reward=0` |
| [SkillsBench](/zh/user_guide/modules/benchmarks/skillsbench) | `score=0`、`passed=false` |
| [Frontier-SWE](/zh/user_guide/modules/benchmarks/frontier_swe) | `score=0`、`correctness=0` |

其他 Benchmark 保留缺少观测的状态。这些值只在 runtime 的评测超时到期时使用，不用于其他评测错误或取消。

## 重试失败的工作

### 哪些 issue 会重试

| 严重级别 | 还有预算时是否重试 |
| - | - |
| FATAL | 始终重试。 |
| ERROR | 仅当 `retry_pattern_list` 中的正则表达式匹配其 `message` 或 `code` 时重试。 |
| WARNING | 从不重试。 |

`max_retries` 设置每个逻辑 attempt 的额外执行次数，setup、执行、收集和评测共享这份预算。默认值为 `0`，即任何失败都不重试：一次瞬时故障（例如 Judge 返回一次 HTTP 503）就会留下最终 FATAL，使该任务失效并导致运行失败。建议设置 `max_retries: 2` 以容忍瞬时服务故障。

模式搜索每个 issue 的 `message` 和 `code`，不搜索 traceback。未填写、`null` 或空的 `retry_pattern_list` 只重试 FATAL。

<Note>
  旧版本在模式列表未填写或为 `null` 时重试所有错误，为空列表时不重试。现在两者都只重试 FATAL。如需重新重试所有 ERROR，请将 `retry_pattern_list` 设为 `[".*"]`。
</Note>

重试无法修复错误的端点、缺失的凭证或无效的配置，需要先修正配置。取消运行或达到整体 `--timeout-seconds` 时限不会触发重试：runtime 不再启动新的重试，并释放已打开的资源。

### 重试会重复什么

重试替换当前逻辑 attempt 内的工作，不增加评分样本数，也不会重跑已完成的其他 attempt。

| 失败发生的位置 | 重试重复的内容 |
| - | - |
| setup、Environment、agent 执行，或结果与产物收集 | 整个 attempt，使用新的任务 Environment 和相同的计划。 |
| `evaluation_environment_mode: none` 下的评测 | 只重试评分，使用已保存的任务输入和 agent 结果。 |
| `evaluation_environment_mode: fresh` 下的评测 | 只重试评分，并新建评测 Environment。 |
| `evaluation_environment_mode: reuse` 下的评测 | 整个 attempt，因为评分共用任务 Environment。 |

每次重试都会把丢弃的结果写入 `attempt-<n>/retries/`，详见[retry 详情](/zh/user_guide/other_features/results/task_results#retry-details)。进度文件会记录 `attempt_retry` 事件，详见 [`progress.jsonl`](/zh/user_guide/other_features/results/run_records#progressjsonl)。

### 重试之间的等待

每次 runtime 重试都会先退避等待。`retry_min_delay_seconds` 默认 `5`，`retry_max_delay_seconds` 默认 `60`；两者须为有限正数，且最大值不小于最小值。退避基准从最小值开始，每次翻倍并在最大值处封顶，默认序列为 `5 → 10 → 20 → 40 → 60 → 60 …` 秒。实际等待均匀随机取本轮基准的 50%～100%，所以第一次默认等待 2.5～5 秒。整轮重跑和仅评测重试共享同一逻辑 attempt 的序列，新 attempt 或新 run 从最小值重新开始。

等待在必要的资源清理后开始，支持取消，计入整次请求的总时限，不计入运行或评测阶段的超时预算。整轮重跑等待时释放并发额度，仅评测重试沿用当前额度。进度阶段显示为 `retry_wait`，选定的等待时长记录在重试诊断与事件的 `retry_delay_seconds` 中。

## 失败对分数的影响

ERROR 和 WARNING 不影响 Benchmark 的有效观测。runtime 从不用 false 或 `0` 填补缺失的观测；只有 Benchmark 自己会给出失败分值，例如上文的 WARNING 和评测超时情形。

任一逻辑 attempt 在重试后仍有 FATAL 时，整个任务失效。该任务在每个指标序列、类别和派生指标中都计为 `invalidated`，其观测全部不参与计算。每个序列满足 `evaluated + unavailable + invalidated = total`，`error` 单独计数。多次 attempt 如何归约见[指标与聚合](/zh/user_guide/other_features/results/metrics_aggregation#明确处理失败与缺失尝试)。

## 运行失败时

只要至少一个任务以最终 FATAL 结束，整次运行即为失败。AgentCompass 仍会写出全部结果文件：

* `metrics.json` 将 `evaluation_failed` 设为 `true`，所有正式 `value` 设为 `null`。`reference_value` 只用未失效的任务计算；没有可评分的任务时也为 `null`。
* `summary.md` 说明没有正式分数，并把其余数值标为参考值。
* `agentcompass run` 以非零状态退出。在 `launch` 中，该请求标记为 `failed`，其他请求继续运行，编排以 `partial_failure` 结束，退出状态为 `1`。
* 在 Python SDK 中，`run_evaluation` 抛出 `RuntimeError`，消息中包含结果路径；`launch` 返回 `OrchestrationResult`，其中该请求标记为 `failed`。

参考值仅用于诊断，不能与正式分数比较。修复原因后，使用 `--reuse` 重新运行，只重做失败的工作。如果任务只有 ERROR 或 WARNING，运行仍然成功并发布正式数值。

## 失败后的复用

[`--reuse`](/zh/user_guide/using_agentcompass/run_controls#继续中断的运行) 会按当前重试策略处理已保存的结果：

* 没有 FATAL、也没有匹配当前模式的 ERROR 的结果直接复用。
* `max_retries` 大于 `0` 时，带有可重试 issue 的 attempt 会重新执行，并占用当前预算中的一次重试。历史重试次数只作为记录保留。
* `max_retries: 0` 时，失败结果原样复用；需要设置重试预算才能重跑。
* 在 `none` 或 `fresh` 评测模式下，如果只有评测失败，会恢复已保存的 agent 结果，不再重新运行 agent。

旧格式的结果在读取时转换。无法根据已保存的证据确定严重级别的历史失败不会被复用，对应任务会重新执行。

## 查找失败详情

| 需要什么 | 在哪里找 |
| - | - |
| 按最终严重级别分组的任务 | 运行目录下的 `details/fatal/`、`details/error/` 和 `details/normal/`；只有 WARNING 的任务位于 `normal`。详见[任务结果](/zh/user_guide/other_features/results/task_results)。 |
| issue 与 traceback | 每个 attempt 的 `issues` 和 `artifacts.execution_diagnostics`。 |
| 丢弃的重试 | 任务目录下的 `attempt-<n>/retries/`。 |
| 运行中的计数 | [`progress.json`](/zh/user_guide/other_features/results/run_records#progressjson) 中的 `failed_tasks`、`error_tasks` 和 `warning_tasks`。 |
| 运行级有效性 | [`metrics.json`](/zh/user_guide/other_features/results/summary_analysis#metricsjson) 中的 `evaluation_failed` 和各序列计数。 |

按照[排查运行失败](/zh/user_guide/other_features/results/run_records#排查运行失败)中的顺序检查这些文件。


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.