3、常见错误码总览：ErrImagePull、ImagePullBackOff、ErrImageNeverPull、ManifestUnknown 等错误码含义

在 Kubernetes 节点上拉取镜像失败时，kubelet 会通过 Pod 状态和事件暴露特定的错误码。理解这些错误码是快速定位故障的第一步。以下按错误严重程度与触发阶段，归纳了最常见的 6 种错误码及其含义。

3.1 错误码速查表

3.2 核心错误码详解

3.2.1 ErrImagePull

这是最直接的拉取失败信号。当 kubelet 执行 crictl pull 或 docker pull 时，如果仓库返回非 200 状态码或网络层报错，Pod 事件中会立即出现 Failed to pull image "xxx": rpc error: code = Unknown desc = ...，对应的错误码即为 ErrImagePull。

• 常见场景：镜像仓库地址写错（如拼写 nginx 为 ngnix）；私有仓库未配置 imagePullSecrets；节点无法解析仓库域名。
• 排查命令：kubectl describe pod <pod-name> 查看 Events 字段中的具体错误信息。

3.2.2 ImagePullBackOff

当 ErrImagePull 发生后，kubelet 不会无限重试，而是进入指数退避（BackOff）状态。首次重试等待 10 秒，之后每次翻倍，上限 5 分钟。此时 Pod 状态显示 ImagePullBackOff。

• 常见场景：镜像标签不存在（如 myapp:latest 实际未推送）；镜像仓库限流（Docker Hub 匿名拉取限制）；节点磁盘空间不足导致无法解压镜像层。
• 注意：ImagePullBackOff 本身不是错误码，而是 kubelet 的重试状态。其底层错误仍然是 ErrImagePull，但增加了退避逻辑。

3.2.3 ErrImageNeverPull

当 Pod 的 imagePullPolicy 设置为 Never 时，kubelet 不会尝试从仓库拉取镜像，仅检查本地是否存在。若本地不存在，则直接报错 ErrImageNeverPull。

• 常见场景：CI/CD 流水线中预拉取镜像后忘记修改策略；节点重启后本地镜像被清理。
• 解决方案：将 imagePullPolicy 改为 IfNotPresent 或 Always，或确保镜像已提前加载到节点。

3.2.4 ManifestUnknown

此错误发生在镜像清单（Manifest）解析阶段。kubelet 成功连接仓库后，请求指定标签的 manifest 时，仓库返回 manifest unknown。通常意味着该标签在仓库中不存在，或镜像仓库的 API 版本不兼容。

• 常见场景：使用 docker pull 时标签存在，但 containerd 或 CRI-O 拉取时因 manifest 格式不同而失败；镜像被删除后重新推送但标签未更新。
• 排查命令：在节点上手动执行 crictl pull <image> 或 ctr image pull <image> 查看详细错误。

3.3 错误码触发流程 SVG

3.4 错误码与 Pod 状态对应关系

在实际排查中，kubectl get pods 显示的 STATUS 列与错误码并不完全一一对应。下表列出了常见的 STATUS 与底层错误码的映射关系：

3.5 错误码与容器运行时的关系

不同的容器运行时（Docker、containerd、CRI-O）在返回错误码时存在细微差异。以下为常见运行时下的错误码映射：