docker pull 出现 422 Unknown 怎么办？
本文适用于：
- • 拉取时出现
unexpected status from HEAD request ... 422 Unknown - • 报错为泛化的 422，且没有明确的 schema 1、manifest unknown 等关键字
- • 已在 Docker Hub 确认镜像存在，但经加速域名拉取仍失败
- • 需与「Schema 1 已废弃」和「manifest unknown」区分
422 Unknown 是什么？
代理向 Docker Hub（或对应上游仓库）查询 manifest 时，上游返回了 HTTP 500 等异常响应，且无法明确判断是「镜像不存在」还是「镜像格式过老（Schema 1）」， 因此返回 422 Unknown，避免误报 404 让用户以为只是 tag 写错。
典型报错示例
docker pull docker.xuanyuan.run/library/php:5.4.39-fpm
Error response from daemon: unexpected status from HEAD request to https://docker.xuanyuan.run/v2/library/php/manifests/5.4.39-fpm: 422 Unknown
域名可能是你的专属加速地址；422 Unknown 是代理层对上游异常的统一封装，需结合镜像本身进一步判断。
常见原因（按概率）
| 原因 | 说明 |
|---|---|
| 镜像版本极老 | 如 php:5.4.39-fpm，上游返回 500 但未命中 Schema v1 的明确识别规则 → 参考 Schema 1 已废弃 |
| 镜像不存在，但上游异常 | Docker Hub 偶发返回 500 而非标准 404，代理无法断定 → 核对 tag 后稍后重试 |
| Docker Hub 临时故障 | 上游短暂不稳定，同一镜像过几分钟可能恢复 |
| 私有 / 受限镜像 | 需登录或权限不足的镜像，上游可能返回非标准错误而非 404 |
建议排查顺序
422 Unknown ↓ 到 Docker Hub 确认镜像名、标签是否存在 ↓ 标签很老（2017 年前后） 参考 Schema 1 文档，换较新版本 ↓ 标签正常、较新 等待 5～10 分钟后重试 ↓ 仍失败 提交工单（附完整 pull 命令与报错）
1）先到 Docker Hub 核对镜像与标签
在浏览器打开对应仓库页面，确认标签是否存在、最后更新时间是否很早。 也可在本站搜索镜像名辅助确认（见 站内搜不到镜像）。
2）若是老版本镜像 → 换新版或自行导入
详见 Manifest Schema 1 已废弃。换镜像源无法解决格式过老的问题。
3）若确认镜像正常 → 等待后重试
Docker Hub 或网络链路偶发异常时，等待 5～10 分钟 后再次执行相同的 docker pull。 避免脚本在短时间内高频重试同一失败标签（可能触发 429 限流）。
4）仍失败 → 提交工单
通过 工单 反馈，请附上：完整 docker pull 命令、完整终端报错、docker version 输出，以及已在 Hub 确认标签存在的截图或链接。
注意：客户端过旧导致的协议问题，通常表现为 406 或 410，而不是 422。 若报错含 OCI index 字样，请参考 406 OCI index 客户端过旧。
你可能还会遇到：
本文由「轩辕镜像」维护
轩辕镜像 | 国内 Docker 镜像加速
内容基于轩辕镜像真实用户使用与实测整理