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

# 故障排查

> 登录、提交、调度、训练与日志的常见问题定位

## 登录与鉴权

<AccordionGroup>
  <Accordion title="sf login 浏览器打不开 / SSH 环境">
    加 `--device-flow` 用设备码登录：CLI 显示一个短码，任意设备浏览器打开提示的 URL 输入即可。CI 场景用 `sf login --token <服务令牌>`。
  </Accordion>

  <Accordion title="401 / token 过期">
    重新 `sf login`。登录态在 `~/.forge/`，多台机器各自登录互不影响。管理员停用账号也表现为 401——先确认账号状态。
  </Accordion>
</AccordionGroup>

## 提交被拒

<AccordionGroup>
  <Accordion title="「recipe 精确契约不一致 / runtime_id 不兼容」">
    实验锁与服务端 catalog 漂移（平台发布了新 recipe）。`sf recipe status <exp>` 看差异，`sf recipe upgrade <exp>` 升级，或提交时加 `--upgrade-recipe`。
  </Accordion>

  <Accordion title="「工作区有未提交改动」">
    平台要求提交可追溯到确切 commit。`git commit` 后重试；确要带脏改动用 `--allow-dirty`（未跟踪文件会列出警告，注意别把大文件 / 敏感文件带上）。
  </Accordion>

  <Accordion title="「config 校验未通过」">
    按报错逐条修：拼错的键（struct 模式不允许新键）、越界的值、批大小整除关系。改完 `sf validate <exp>` 本地确认再提交。
  </Accordion>

  <Accordion title="「HuggingFace 资源预检未通过」">
    config 引用了 gated 模型 / 数据集而你的 HF 账号未获授权，或 dataset id 拼错（需 `org/name` 全名）。先在 HF 网站申请访问，再到控制台 HuggingFace 页确认已关联账号。
  </Accordion>

  <Accordion title="「镜像 registry 不在 allowlist」（custom）">
    custom 的 `--image` 可用 tag；生产钉 `@sha256:…`。仓库主机必须在 `FORGE_ALLOWED_IMAGE_REGISTRIES`。名单为空时自定义用户镜像一律拒绝。[自定义镜像](/zh-Hans/guides/custom-images)。
  </Accordion>

  <Accordion title="custom external observability 要求 spec.framework.observability_url">
    catalog 的 `custom/custom` 是 `external` 观测。提交加 `--observability-url`。控制台曲线仍要 `starforge.report`（镜像里装 `starforge-core`）。[自定义训练](/zh-Hans/guides/custom-training)。
  </Accordion>

  <Accordion title="train.sh 立刻 exit 1 / 2">
    脚手架脚本在提示你还没填训练命令。换掉它。工作目录是 `FORGE_WORK_DIR`；跑 `"${FORGE_EXP_DIR}/train.py"`。
  </Accordion>

  <Accordion title="配额不足">
    提交会进入队列而不是失败；`sf status` 看当前占用。着急就 `sf job stop` 释放自己的旧作业，或找管理员调配额。
  </Accordion>
</AccordionGroup>

## 作业异常

<AccordionGroup>
  <Accordion title="一直 QUEUED 不出队">
    依次排查：配额水位（`sf status`）、集群空闲卡（控制台仪表盘）、时段窗口是否关闭（窗口剩余不足阈值不放行）、维护模式是否开启。
  </Accordion>

  <Accordion title="PENDING 卡住（kuberay）">
    多为拉镜像慢 / 没有满足 nodeSelector 的节点 / GPU 不足。作业详情的**事件**里有 K8s Event 原文；超过 preRunning 期限会自动判失败。
  </Accordion>

  <Accordion title="RUNNING 但图表没数据">
    先看**日志** tab，确认训练真的在跑（可能还在装模型）。日志正常、指标没有：部署侧 `FORGE_INGEST_URL` 必须是训练容器能访问的地址（不能是 127.0.0.1）。custom 作业还要确认训练代码调用了 `starforge.report`，见[自定义训练](/zh-Hans/guides/custom-training)。
  </Accordion>

  <Accordion title="FAILED 后自动出现新作业">
    这是自动重试（预算内、带冷却）。作业详情可见重试计数；不想重试可在失败后手动 stop。
  </Accordion>

  <Accordion title="OOM / 容器被杀">
    作业详情失败原因标注「OOM killer」时：降 `train_micro_batch_size`、开 activation checkpointing、降 vLLM `gpu_memory_utilization`，或换更大形状的 profile。**诊断** tab 的 AI 分析通常直接给出建议改法。
  </Accordion>
</AccordionGroup>

## 日志与观测

<AccordionGroup>
  <Accordion title="sf job logs 断流">
    SSE 断线 CLI 自动重连续传；持续断流看反代配置（nginx 需对 `/api` 关闭缓冲）。历史日志随时可回放：`sf job logs <ID> -n 0`。
  </Accordion>

  <Accordion title="验证样本是空的">
    确认方法有验证环节（`val_period` > 0）且已到验证步；GRPO/PPO 的样本在验证轮生成，训练刚起步时为空是正常的。
  </Accordion>
</AccordionGroup>

还没解决？控制台作业详情 → **诊断** 跑一次 AI 诊断，或把 run id 交给管理员查服务端日志。