常见错误

先保留完整错误文本，再区分配置错误与某个 Pin 的运行失败。nix-pins status 可查看已有结果和上次失败信息。

配置加载失败

• 检查当前工作目录、--config 和 --pins。
• 确认 <nixpkgs> 可解析，运行 nix eval --impure --raw --expr 'toString <nixpkgs>'。
• 检查目标字段：target 不能与旧字段混用，GitHub 目标必须是 owner/repo。
• pin.fetcher.url 和 pin.fetcher.zip 的 URL 必须是函数，例如 version: "https://..."，不能直接写字符串。
• rev 映射也必须返回字符串；不支持的字段会报错。

确定性的配置错误发生在 Checker 执行前，修正声明后再更新。

版本检查失败

GitHub 的 403／429 可能为 API 限流。按运行配置提供 token，勿将 token 写进会提交的文件。

Git 检查依赖 git ls-remote。检查网络、目标权限和 mode；branch 需要 branch，ref 需要 ref。tag 模式无候选时检查正则与仓库是否真的有 tag。

npm Checker 读取 dist-tags。指定的 distTag 不存在时会失败。URL Checker 无匹配时检查文本响应和正则；命令 Checker 必须成功退出并输出非空版本。

获取来源失败

核对 Checker 的原始 Version 与上游 tag、提交号或文件名是否对应。注册表版本可能需要 rev 或 url 映射，不要修改 Pins File 中的版本来绕过配置问题。

确认所用 Nixpkgs 提供对应 Fetcher，尤其是 fetchFromHuggingFace。大模型、子模块和访问受限仓库还需要相应容量、网络和凭证条件。

依赖哈希失败

检查 Package 的 root 和锁文件位置。npm 需要 package-lock.json；pnpm 需要兼容的 pnpm-lock.yaml、显式 fetcherVersion，以及与下游一致的 pnpm 版本。

预取依赖会实际执行中间 FOD 的构建步骤，失败不一定是最终应用的构建问题。检查输出指向的 Source、Package 与依赖 Hash，随后只更新对应 Pin。

Reader 失败

确认 Pins File schema 为 v2，并使用 pins.<pin>.sources.<source>.src。需要 packages 或补丁源码时同时提供 config。变更配置后应更新 Pins File，确保新声明和锁定结果一致。

同时运行与取消

写锁冲突表示另一个进程正在更新同一 Pins File。等待它完成后重试；不要在仍有写者运行时绕过锁。取消不会写入本轮结果，已有 Pins File 可继续使用。

如果下载和构建压满本地资源，降低 download_jobs 与 hash_jobs。交互式 TUI 与 CI 文本输出不同，应以退出码、错误文本和 Pins File 判断业务结果。