# 排错与安全重试

| 现象 | 核对与处理 |
| --- | --- |
| 编译失败或旧清单错误 | 先运行 `moon version --all`，使用基准 0.10.17+d971670cd 或已验证的新版本；运行 `moon update`，不要从另一份 SDK 混用 core 文件 |
| Node 文件命令不能运行 | 确认 `node --version` 至少 22.3；命令包含 `--target js`，或先 `moon build --target js` 再运行对应 JS 入口 |
| `output already exists` / EEXIST | 使用新文件名，先核对现有文件用途；没有隐式强制覆盖开关 |
| `output published; ...` | 目标已完成发布但清理失败；先完整校验现有目标，再处理本次暂存残留；不要盲目重试或删除目标。提交点见 [架构](architecture.md) |
| ENOENT / 父目录不存在 | 确认当前目录、输入、输出父目录；路径带空格时整体加引号；以 `--` 开头的输入放在选项结束符之后 |
| 超过预算或不支持的格式 | 先核对错误属于编码记录、解压块、完整载入、缓存还是输出预算；按实际资源调整对应项，或选择流式入口。不要把某一预算当作总 RSS 限制 |
| `--format` 或预算参数被拒绝 | 参数只适用于消费它的入口；二进制输出不接受报告格式参数，索引/任务操作不接受无效的完整载入预算，详见 [CLI](cli.md) |
| 查询成功但完整校验失败 | 快速查询不检查未读取的数据；使用 `validate` 或 `--full` 获取完整结果，详见 [校验边界](scope.md) |
| 标准输出中已有几行，随后失败 | 流式 stdout 无法撤回。检查退出码；需要完整成功后才可见的结果，使用 `--output` 文件 |
| 退出 0 但标准错误有恢复报告 | `recover` 的报告写到 stderr；核对 recovered_messages、stop_offset、complete，成功的部分恢复不是完整修复 |
| 任务拒绝恢复 | 输入、规则、代码、环境或已完成输出可能改变；保留原 job 和现场，核对具体错误。改动后的处理应新建 job，不编辑检查点以强行继续 |
| 锁被占用 | 先确认原进程或子进程是否仍运行；按对应任务协议等待/恢复。不要在活动进程运行时删除锁或提交文件 |
| 硬链接发布失败 | 输出目录可能位于不支持硬链接的文件系统；改用支持同目录硬链接的本地文件系统。工具不会退回覆盖写入 |
| 公开语料下载或指纹失败 | 网络失败可恢复连接后重试；指纹变化须核对发布方与清单，不能移除 SHA-256 校验 |

通用 `cmd/mcap` 退出码：0 成功，1 为 validate 无效文件或 diff 检出差异，
2 为参数/执行错误。其他入口有独立的业务退出码，详见各自文档；不要统一按
stderr 是否为空或输出文件是否存在来判断成功。

问题反馈建议包含：模块版本、moon/Node 版本、目标平台、经过脱敏的命令和
错误 JSON、输入格式/压缩、是否能用仓库合成样例复现。原始录制可能包含敏感内容，
无需随问题上传；可先使用最小合成文件描述同一格式问题。