manifest unknown 错误

本文适用于：

• Docker 20+ / 24+（低版本可能导致此错误）
• 国内网络环境
• 拉取镜像时遇到 manifest unknown 错误
• 需要验证镜像是否存在或 Docker 版本是否兼容

⚠️ 重要提示

这通常不是网络问题，而是镜像不存在或 Docker 版本过低。

快速诊断流程：

manifest unknown 错误
  ↓
检查 Docker 版本（docker info）
  ↓ 版本 < 20
升级 Docker（主要原因）
  ↓ 版本 >= 20
验证镜像名和标签是否存在

✅ 推荐做法

优先检查 Docker 版本，Docker 20+ 是使用现代镜像仓库的前提。确认版本后，再验证镜像信息是否正确。

当您遇到 manifest unknown 错误时，需要先检查 Docker 版本，然后确认镜像信息是否正确。

错误示例

root@btpanel:~# docker pull docker.xuanyuan.run/nodebb/nodebb:latest Error response from daemon: manifest for docker.xuanyuan.run/nodebb/nodebb:latest not found: manifest unknown: manifest unknown

问题排查步骤

步骤 1：检查 Docker 版本

首先执行 docker info 查看 Server Version：

docker info | grep "Server Version"

如果版本低于 20.x，请先升级 Docker 到 20+ 版本。因为 Docker 不同版本支持的 Registry API 协议不同，低版本客户端在拉取镜像时可能不兼容 v2 接口。

步骤 2：确认镜像信息

如果 Docker 版本已经是 20+，仍然报错，这表示镜像仓库中不存在指定的镜像名或标签（tag）。

常见原因包括：

• 镜像名称拼写错误
• 指定的标签（tag）不存在
• 镜像已被删除或下架

解决方案

方案 1：升级 Docker（如果版本过低）

参考 Docker 升级文档：

https://xuanyuan.cloud/install/linux

方案 2：验证镜像信息（如果版本已是最新）

请先在本站镜像仓库页面搜索该镜像，确认镜像名与标签（tag）是否正确。

使用页面提供的完整拉取命令执行 docker pull。

示例

假设网站查询到正确的镜像信息为：

镜像名：elestio/nodebb

标签：v4.4.6

则拉取命令为：

docker pull docker.xuanyuan.run/elestio/nodebb:v4.4.6

💡总结：遇到 manifest unknown 错误时，先检查 Docker 版本，版本过低则升级；版本正常则验证镜像信息是否正确。这样可以快速定位和解决问题。

你可能还会遇到：

本文由「xuanyuan.cloud」维护
专注国内 Docker / 镜像 / Registry 网络问题
内容基于真实用户环境与实测