故障排查与 FAQ

本页内容来自 README 的部署注意事项、AGENTS.md 的约定、v0.1 深度测试报告（docs/06-deep-testing.md）中已修复的真实缺陷，以及 packages/ 代码里的错误路径。所有命令都可以在 CLI 或 MCP 客户端里执行。

任务提交与调度

1. job 长时间 QUEUED 不派发

症状：list_jobs(status="QUEUED") 里任务一直在排队。
原因：
- 没有空闲 GPU 槽位；cpu_only 车道有并发上限；node_selector 不匹配。
- 队首是一个需要多 GPU 的任务，后面的 cpu 任务也会被挡住（调度器单 tick 派发一个）。

处置：

uv run gpuctl node status                    # 看哪些 GPU 空闲
uv run gpuctl job list --status QUEUED       # 确认队列

检查 job 的 resources 和 node_selector；如果不急，可提高 priority。

2. 启动即 DISPATCH_FAILED / working_dir 错误

症状：job 瞬间 FAILED，failure_reason=DISPATCH_FAILED。
原因：
- working_dir 在 agent 主机上不存在（注意：CLI/MCP 不会把本机路径改写到 agent 主机，必须传 agent 能解析的绝对路径）。
- command[0] 不存在或没有执行权限。
- runner=docker 但没填 image。
处置：登录 agent 主机执行：
Terminal window
```
ls -d /path/to/working_dir
which python
docker images | grep <image>
```
跨机提交前先 ssh agent-host ls /path 确认。

3. 提交报 422 validation_error

症状：submit_job 返回 422。
原因：参数越界，例如 priority/before 超过 MAX_I64_SAFE（2^62）、gpu<0、name=""、max_attempts<1。
处置：对照错误详情修正参数。limit、tail 等分页参数必须 ≥1。

4. 命令带交互式参数导致卡住

症状：job 状态 RUNNING 但永远没完，日志停在某个输入提示。
原因：训练命令带了 -i、--pdb、python -、REPL 等交互式参数，占住槽位。
处置：cancel_job(confirm=True) 后改为 headless 命令；永远不在 job 里用 --pdb。

指标与日志

5. Run Detail 看不到指标

症状：Web/MCP 里 run 的指标为空或图表空白。
原因：
- 训练脚本没有写 TensorBoard 事件，也没有用 SDK run.log。
- 提交 TRAIN job 时没传 --watch 或 watch_dirs，checkpoint watcher 没覆盖到 TB 目录。
- 指标名不在 server 认识的命名空间里（如没有 train/ 或 eval/ 前缀）。

处置：

uv run gpuctl run show <run-id>              # 看 summary 有没有 latest
uv run gpuctl event list --run-id <run-id>   # 看有没有 LOSS_NAN 等事件

在 agent 上检查 working_dir 下是否存在 .tfevents 文件。

6. latest 显示 non-finite

症状：指标卡片出现红色 non-finite，对应曲线断开。
原因：loss 或指标出现了 NaN/Inf。
处置：查看事件流 LOSS_NAN；检查学习率、AMP、loss scaling、输入数据；必要时用 diagnose_run 看趋势。

7. 日志只有 2000 行，看不到完整输出

症状：tail_logs 只能拿到最近 N 行。
原因：server 只在 SQLite 里保留尾部（默认 2000 行），完整日志在 agent 本地。

处置：到 agent 主机查看：

ls ~/.gpuctl/jobs/<job-id>/attempt-<n>/stdout.log
tail -n 5000 ~/.gpuctl/jobs/<job-id>/attempt-<n>/stderr.log

8. TensorBoard 事件没被抓到

症状：训练脚本写了 TB，但 GPUPlane 没指标。
原因：TB 目录不在 watch_dirs；或事件文件刚写完还没来得及扫描。
处置：提交时显式指定 --watch / watch_dirs；在 agent 上 ls working_dir/*tfevents* 确认文件存在。

训练失败

9. OOM（最常见的失败）

症状：job FAILED，failure_reason=OOM，事件流有 OOM critical。
原因：CUDA out of memory。
处置：
1. 先调用 explain_failure(run_id) 看结构化建议。
2. 改小 batch、启用 gradient checkpointing/accumulation、释放显存。
3. 不要直接 retry_job——未改配置会同样失败；应 submit_job 一个新 job 或改完原 job 配置后再重试。

10. 非 OOM 的 EXIT_CODE / SIGNAL

症状：FAILED，failure_reason=EXIT_CODE 或 SIGNAL(11)。
原因：代码异常、segfault、被信号终止等。

处置：

uv run gpuctl logs -f <job-id> --stream stderr
uv run gpuctl run explain-failure <run-id>

修复代码后提交新 job；未修复的 retry_job 会同样失败。

11. LOSS_NAN

症状：事件流出现 LOSS_NAN critical，指标 latest 为 null。
原因：训练过程出现非有限 loss。
处置：降学习率、检查 AMP/loss scaling、清洗输入数据；参考事件与诊断。

12. 评估报 EVALUATION_RESULT_INVALID

症状：EVALUATE job exit 0 但 FAILED，failure_reason=EVALUATION_RESULT_INVALID。
原因：eval 脚本没有按约定写 {"metrics": {...}} 到 GPUCTL_EVAL_OUTPUT。
处置：在 agent 上读取 ~/.gpuctl/jobs/<job-id>/attempt-<n>/eval_result.json，确认 JSON 形状。

13. checkpoint 路径被多个 run 共享

症状：创建评估时返回 409 Conflict：checkpoint path is shared by multiple runs。
原因：同一个文件路径被不同 run 写入，可能互相覆盖，评估结果不可信。
处置：让训练脚本把 checkpoint 写到 run-scoped 目录，例如 checkpoints/run_xxx/epoch_N.pt。

连接与部署

14. Agent 离线 / JOB_LOST

症状：节点状态 OFFLINE，RUNNING 任务变成 LOST，事件流有 AGENT_DISCONNECTED/JOB_LOST。
原因：agent 崩溃、网络断开、server 检测不到心跳。
处置：
Terminal window
```
systemctl --user status gpuctl-agent   # 或你用的 supervisor
journalctl --user -u gpuctl-agent -n 100
```
如果只是网络抖动，agent 重连后 reconcile 会恢复任务；如果是崩溃，任务标 LOST 后用 retry_job 重新排队。

15. 401 / 403

症状：API/MCP 调用返回 missing or invalid token 或 scope insufficient。
原因：token 缺失、错误、过期；或用了 read-scope token 调 write 接口。
处置：
Terminal window
```
curl -s http://gpu-host:8600/api/v1/auth/whoami \
  -H "Authorization: Bearer $TOKEN"
```
写操作（submit/cancel/retry/evaluate/set_primary_metric）需要 write-scope token；作业内的 GPUCTL_TOKEN 是 sdk-scope，只能 ingest。

16. WSL2 / Docker 容器看不到 GPU

症状：docker run --gpus all nvidia/cuda nvidia-smi 报错，或 GPU job 在容器里 OOM/找不到 CUDA。
原因：
- WSL2 宿主本身没有正确透传 GPU（先确认 Windows 侧 nvidia-smi）。
- 没安装 NVIDIA Container Toolkit 或 runtime 未写入 Docker 配置。

处置：

nvidia-smi                                    # 宿主必须有 GPU
sudo nvidia-ctk runtime configure --runtime=docker
sudo systemctl restart docker
docker run --rm --gpus all nvidia/cuda nvidia-smi

17. DISK_LOW 事件

症状：事件流出现 DISK_LOW critical。
原因：输出盘剩余空间 < 5%。
处置：
Terminal window
```
df -h /path/to/working_dir
```
清理旧 checkpoint、改输出目录、或扩容磁盘。

18. SDK 本地 spool 文件不断累积

症状：~/.gpuctl/spool/ 里有很多 sdk-*.jsonl。
原因：训练脚本在平台外跑，且 server 不可达或没有 token。
处置：确认 GPUCTL_SERVER 和 GPUCTL_TOKEN 正确；一旦恢复在线，spool 会先重放再发新数据。长期离线属于设计内行为。

快速诊断命令速查

# 节点与队列总览
uv run gpuctl status

# 单个 run 的语义摘要
uv run gpuctl run show <run-id>

# 失败分析
uv run gpuctl run explain-failure <run-id>

# 实时日志
uv run gpuctl logs -f <job-id>

# 事件流
uv run gpuctl event list --severity critical

# agent 本地完整日志（在 agent 主机上）
ls ~/.gpuctl/jobs/<job-id>/attempt-<n>/