登录与鉴权
sf login 浏览器打不开 / SSH 环境
sf login 浏览器打不开 / SSH 环境
加
--device-flow 用设备码登录：CLI 显示一个短码，任意设备浏览器打开提示的 URL 输入即可。CI 场景用 sf login --token <服务令牌>。401 / token 过期
401 / token 过期
重新
sf login。登录态在 ~/.forge/，多台机器各自登录互不影响。管理员停用账号也表现为 401——先确认账号状态。提交被拒
「recipe 精确契约不一致 / runtime_id 不兼容」
「recipe 精确契约不一致 / runtime_id 不兼容」
实验锁与服务端 catalog 漂移（平台发布了新 recipe）。
sf recipe status <exp> 看差异，sf recipe upgrade <exp> 升级，或提交时加 --upgrade-recipe。「工作区有未提交改动」
「工作区有未提交改动」
平台要求提交可追溯到确切 commit。
git commit 后重试；确要带脏改动用 --allow-dirty（未跟踪文件会列出警告，注意别把大文件 / 敏感文件带上）。「config 校验未通过」
「config 校验未通过」
按报错逐条修：拼错的键（struct 模式不允许新键）、越界的值、批大小整除关系。改完
sf validate <exp> 本地确认再提交。「HuggingFace 资源预检未通过」
「HuggingFace 资源预检未通过」
config 引用了 gated 模型 / 数据集而你的 HF 账号未获授权，或 dataset id 拼错（需
org/name 全名）。先在 HF 网站申请访问，再到控制台 HuggingFace 页确认已关联账号。「镜像 registry 不在 allowlist」（custom）
「镜像 registry 不在 allowlist」（custom）
custom 的
--image 可用 tag；生产钉 @sha256:…。仓库主机必须在 FORGE_ALLOWED_IMAGE_REGISTRIES。名单为空时自定义用户镜像一律拒绝。自定义镜像。custom external observability 要求 spec.framework.observability_url
custom external observability 要求 spec.framework.observability_url
catalog 的
custom/custom 是 external 观测。提交加 --observability-url。控制台曲线仍要 starforge.report（镜像里装 starforge-core）。自定义训练。train.sh 立刻 exit 1 / 2
train.sh 立刻 exit 1 / 2
脚手架脚本在提示你还没填训练命令。换掉它。工作目录是
FORGE_WORK_DIR；跑 "${FORGE_EXP_DIR}/train.py"。配额不足
配额不足
提交会进入队列而不是失败；
sf status 看当前占用。着急就 sf job stop 释放自己的旧作业，或找管理员调配额。作业异常
一直 QUEUED 不出队
一直 QUEUED 不出队
依次排查：配额水位（
sf status）、集群空闲卡（控制台仪表盘）、时段窗口是否关闭（窗口剩余不足阈值不放行）、维护模式是否开启。PENDING 卡住（kuberay）
PENDING 卡住（kuberay）
多为拉镜像慢 / 没有满足 nodeSelector 的节点 / GPU 不足。作业详情的事件里有 K8s Event 原文；超过 preRunning 期限会自动判失败。
RUNNING 但图表没数据
RUNNING 但图表没数据
先看日志 tab，确认训练真的在跑（可能还在装模型）。日志正常、指标没有：部署侧
FORGE_INGEST_URL 必须是训练容器能访问的地址（不能是 127.0.0.1）。custom 作业还要确认训练代码调用了 starforge.report，见自定义训练。FAILED 后自动出现新作业
FAILED 后自动出现新作业
这是自动重试（预算内、带冷却）。作业详情可见重试计数；不想重试可在失败后手动 stop。
OOM / 容器被杀
OOM / 容器被杀
作业详情失败原因标注「OOM killer」时：降
train_micro_batch_size、开 activation checkpointing、降 vLLM gpu_memory_utilization，或换更大形状的 profile。诊断 tab 的 AI 分析通常直接给出建议改法。日志与观测
sf job logs 断流
sf job logs 断流
SSE 断线 CLI 自动重连续传；持续断流看反代配置（nginx 需对
/api 关闭缓冲）。历史日志随时可回放：sf job logs <ID> -n 0。验证样本是空的
验证样本是空的
确认方法有验证环节（
val_period > 0）且已到验证步；GRPO/PPO 的样本在验证轮生成，训练刚起步时为空是正常的。